rcf-lite 0.11.0 → 0.13.0

package/blueprints/observability-essentials/docs/topics.md

@@ -0,0 +1,57 @@
+# observability-essentials blueprint coordination vocabulary
+
+This file is the observability-essentials half of the cross-blueprint contract. The Phase 1 conflict detector matches scope:global ADR topics by EXACT string equality, and AC ids are unnamespaced by the 0.4.4 grammar. Any blueprint intended to compose with this one must reuse these exact strings and respect these bands.
+
+## Global ADR topics this blueprint contributes (exact strings)
+
+| Topic string | observability-essentials contribution | Origin | Composition note |
+|---|---|---|---|
+| `healthProbes` | ADR-801-observability-essentials-health-probes | Minted here; pre-cleared as unclaimed against application-spa (`clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel`), application-api-rest (`errorEnvelope`, `authModel`, `apiVersioning`, `logging`), security-auth-magic-link (`authModel`), persistence-data-sqlite (`persistenceStore`, `migrationDiscipline`), ci-pipeline (`ciGates`, `strictCoverageGate`), and the hello-panel walkthrough exemplar (`operatorPanel`) | The one HTTP health probe contract for the project: two endpoints (liveness /healthz, readiness /readyz), shared JSON body shape, served on the request-traffic listener. A composing blueprint that holds a different endpoint contract (a single /health endpoint, gRPC health protocol, probes on a separate admin port) contributes its own scope:global ADR on this exact string and lets composition surface the pairing. Expected resolution: one project-level ADR that fixes the endpoint contract |
+| `readinessSemantics` | ADR-802-observability-essentials-readiness-semantics | Minted here; pre-cleared as unclaimed against application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, ci-pipeline, and hello-panel | The one readiness aggregation and declaration scope for the project: strict-any-fail over an explicit boot-time-declared dependency set, evaluated against per-dep cached state. A composing blueprint that holds a different opinion (quorum aggregation, write-path-only readiness, graceful-degradation model) conflicts here by design. Expected resolution: one project-level ADR fixing the semantics |
+| `statusPageContract` | ADR-803-observability-essentials-status-page-contract | Minted here; pre-cleared as unclaimed against application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, ci-pipeline, and hello-panel | The one public status page contract for the project: declared component list plus fixed state enum plus stable-fielded incident notices. A composing blueprint that wants a different public contract (JSON endpoint at /status.json, historical uptime cells as v1 requirement, webhook-posted notices) conflicts here by design. Expected resolution: one project-level ADR fixing the public contract |
+
+The observability-essentials blueprint claims three global topics. Every other contribution is scope-local (ADR-804 probe secrecy and ADR-805 notification outcome model do not contribute global topics; a composing blueprint that holds an opinion on probe auth policy or notification outcome shape authors its own project-level ADR if it wants to override).
+
+Note on the delineation from the hello-panel walkthrough's `operatorPanel` topic: `operatorPanel` (owned by the hello-panel walkthrough exemplar) governs the project's PRIMARY operator drift-detection surface, an AUTHENTICATED surface for the operator. This blueprint's status page (ADR-803) governs the PUBLIC status surface for external readers. The two surfaces are deliberately distinct in audience and vocabulary; this blueprint MUST NOT touch `operatorPanel` and does not contribute an ADR on it.
+
+Note on the delineation from the application-api-rest blueprint's `logging` topic: `logging` (owned by application-api-rest ADR-304) governs the wire-log shape of the HTTP tier. This blueprint's notification outcome sink (ADR-805) is a durable record surface for notification attempts, not a log; the two do not overlap.
+
+Note on the delineation from the persistence-data-sqlite blueprint's `persistenceStore` topic: this blueprint's notification outcome sink is substrate-agnostic. When composing with the persistence-data-sqlite blueprint, the outcome sink's substrate is a facade verb on that store; the observability-essentials blueprint does not itself hold an opinion on the store engine and does not conflict on `persistenceStore`.
+
+Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, and persistence vocabularies, restated as law): lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer. Do not mint variants of existing strings (`healthEndpoints`, `probes`, `livenessReadiness` are all wrong when `healthProbes` already exists; `readinessAggregation`, `readyPolicy` are all wrong when `readinessSemantics` already exists; `statusPage`, `publicStatus`, `uptimePage` are all wrong when `statusPageContract` already exists).
+
+## Id number bands (registry bootstrap)
+
+AC ids (and therefore US numeric ids, which anchor them) are NOT namespaced by the 0.4.4 schema grammar; the band allocation IS the AC-collision enforcement mechanism. Composing blueprints take a fresh band rather than proposing namespaced AC ids. Band allocation is ratified policy (2026-08-19); this table is the shared registry-bootstrap replicated across every shipped and forthcoming blueprint's `docs/topics.md` until a mechanism-side central registry lands (v1.1 candidate).
+
+This table is maintained shelf-wide across every blueprint's `docs/topics.md`. Rows are recorded at ship, never predicted.
+
+| Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
+|---|---|---|---|---|
+| application-spa | 1101-1899 | 2xx | shipped v1.3.0 | `clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel` |
+| application-api-rest | 2101-2899 | 3xx | shipped v1.0.0 | `errorEnvelope`, `authModel`, `apiVersioning`, `logging` |
+| security-auth-magic-link | 3101-3899 | 5xx | shipped v1.0.0 | `authModel` |
+| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
+| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
+| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| ci-pipeline | 6101-6899 | 7xx | shipped v1.0.0 | `ciGates`, `strictCoverageGate` |
+| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
+| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
+| security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
+| security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
+| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
+| persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics` |
+
+US 7101-7110 sit at the LOW end of the 7101-7899 band on purpose. A project-side story that mechanically derives from an observability-essentials REQs id into the number `7110` would collide against observability-essentials-US-7110 in this package; the band leaves headroom at the HIGH end (US 7181-7899) so a project's own stories anchored to observability-essentials REQs can allocate without conflict. The watchpost run4 lesson applies here too.
+
+Row-status caveat: the ci-pipeline seat shipped first (PR #95 merged at 595cab9c on main). This branch was rebased onto that main; the ci-pipeline row reflects the shipped state, and the observability row flips to `shipped v1.0.0` at this branch's merge (Dave coordinates that final flip in the merge commit or an immediate follow-up).
+
+## Shared expectations for future composing blueprints
+
+- Reuse `healthProbes` exactly as spelled here when your blueprint holds an opinion on the health endpoint contract; contribute your own scope:global ADR on that string and let composition surface the pairing. A gRPC-health blueprint or a single-endpoint blueprint will conflict here by design.
+- Reuse `readinessSemantics` exactly as spelled here when your blueprint holds an opinion on readiness aggregation or the declaration scope; a quorum-aggregation blueprint conflicts here by design.
+- Reuse `statusPageContract` exactly as spelled here when your blueprint holds an opinion on the public status surface; a machine-readable JSON-endpoint blueprint or a historical-uptime blueprint conflicts here by design.
+- This blueprint's decision states the two-endpoint HTTP JSON contract, the strict-any-fail explicit-declaration readiness semantics, and the declared-component fixed-enum status page. Compose compatible metrics-export, tracing, or authenticated-operator-dashboard blueprints, or expect the operator to supersede with one project-level ADR per topic.
+- Global topics that plausibly belong to a future blueprint and are NOT claimed by any shipped blueprint: `messageSerialisation` and `deliverySemantics` (a message-consumer blueprint's natural globals), `caching` (unclaimed by every shipped blueprint), `metricsExport` and `tracingProtocol` (natural globals for a metrics or tracing blueprint that would compose alongside this one). Define any of these in your own package's topics doc, in this file's format, and consider whether the band-registry table above needs your slug added.

package/blueprints/observability-essentials/guide/observability-essentials.md

@@ -0,0 +1,68 @@
+# Observability blueprint guide
+
+## What it is
+
+A default observability floor for small greenfield rcf-lite projects. The blueprint contributes the WHAT of an observability pattern: how the process advertises liveness to its orchestrator, how it advertises readiness to its load balancer, how external readers see the current state of the service on a public status page, and how the project records the outcome of every notification it attempts. The default endpoint shape is HTTP with a stable JSON body; metrics export, distributed tracing, and log shipping are documented future variants behind their own future blueprints.
+
+Concretely, the blueprint ships ten requirements, ten user stories (thirty acceptance criteria), four architecture components, and five architecture decision records. Three ADRs are `scope: global` on the topics `healthProbes` (the two-endpoint HTTP JSON contract), `readinessSemantics` (strict-any-fail over an explicit boot-time-declared dependency set with cached per-dep state), and `statusPageContract` (the declared component list, the fixed state enum, and the stable notice fields on the public status page); the other two are scope-local operational ADRs (probe secrecy, notification outcome model) that a composing blueprint does not conflict with by default.
+
+## What it is not
+
+Not a metrics-export surface. There is no Prometheus scrape endpoint, no StatsD emission, no OpenTelemetry metrics contract. Projects that need metrics wire them in project-side or wait for a future `metrics-export` blueprint that composes alongside this one.
+
+Not a distributed-tracing surface. There is no span emission contract, no propagation rules, no sampling policy. A future `tracing` blueprint composes alongside this one; until then, projects that need distributed tracing supersede with a project-level ADR or add a project-authored tracing surface.
+
+Not a log-shipping surface. The application-api-rest blueprint's `logging` topic governs the wire-log shape of the HTTP tier; this blueprint does not extend or conflict with that. Notification outcome records are a durable record surface, not a log.
+
+Not an authenticated operator dashboard. The readiness probe body exposes granular per-dependency state for operator consumption, but a rich UI for internal state (per-endpoint metrics, per-request tracing, live event streams) is out of scope; projects that need it author it on top of the readiness surface and their own authenticated dashboards.
+
+Not a historical uptime chart on the status page. The public status page renders current state only at v1.0.0 (see the README's Known mechanism-reach gaps). Projects that need historical uptime cells layer them on top of a project-owned metrics substrate; a future `metrics-store` blueprint or persistence-event-log-fed variant lifts this into an AC at v1.1.
+
+Not an operator drift-detection panel. The hello-panel walkthrough exemplar's `operatorPanel` topic (authenticated persistent operator status panel above the main content) is deliberately distinct from this blueprint's `statusPageContract`; the two surfaces have different audiences (operator vs external reader) and different vocabularies. A project that wants both applies both blueprints and lets them compose.
+
+## When to reach for it
+
+Reach for the observability-essentials blueprint when:
+
+- The project is a small greenfield rcf-lite deployment (single deployable, one small team, one host or a small container fleet, no ops team standing by).
+- The deploy target runs under an orchestrator that consumes HTTP health probes (Kubernetes, systemd with sd_notify or an http-check add-on, a container platform with an equivalent probe contract).
+- The service has external readers (customers, partners, anonymous visitors) who need a canonical answer to 'is this up right now' without opening a support ticket.
+- The project sends notifications (email, SMS, push, webhook) to human recipients and needs to answer 'did the customer get it' from a queryable record rather than by hunting a provider dashboard.
+- The observability posture is 'start with the two-endpoint HTTP contract plus a public status page, layer metrics and tracing in later'; the blueprint's contract survives that layering, because the probe endpoints are the orchestrator's floor and everything else composes above them.
+
+## When it does not fit
+
+Do not reach for the observability-essentials blueprint when:
+
+- The orchestrator does not consume HTTP probes and cannot be reconfigured to (a proprietary orchestration substrate with a fixed non-HTTP health contract, a gRPC-first application on a gRPC-only mesh). A project with these needs supersedes ADR-801 with a project-level ADR selecting the orchestrator's native probe surface; the readiness semantics (ADR-802) and the status page contract (ADR-803) are transport-agnostic and carry over.
+- The service has no external readers and no public status contract is needed (an internal-only tool consumed only by authenticated operators). A project with these needs applies the blueprint with the status page path unrouted or supersedes ADR-803 with a project-level ADR declining the public surface. The probes stay useful.
+- The service sends no notifications (a read-only API, a batch-only pipeline). A project with these needs applies the blueprint without wiring TAC-804 into any code path; the notification outcome sink is dormant.
+- The observability posture is metrics-first or tracing-first (a project that has already committed to OpenTelemetry end-to-end and does not want a lightweight two-probe HTTP floor on top). A project with these needs supersedes the health probe ADR with a project-level ADR mapping to the OpenTelemetry contract; the notification outcome sink and the public status page contract stay useful.
+- The project needs multi-region status roll-up on the public page (per-region component state, per-region incident notices). Out of scope at v1.0.0; a future `multi-region-status` blueprint composes alongside this one, or a project supersedes ADR-803 with a project-level ADR extending the component vocabulary to include region.
+
+The design brief `w-2026-07-28-029` originally scoped observability as one of the five stock blueprint categories for the ergonomics ship gate. The observability-essentials blueprint at v1.0.0 does not include metrics export or distributed tracing because both are separate decision areas with their own contract surfaces (metrics-export names the wire format for a scrape or push; tracing names the propagation and sampling policy); folding them into one blueprint would produce a package with four global topics that a project has to resolve piecewise. Shipping the two-endpoint HTTP contract plus the public status page plus the notification outcome sink is the shape that fits the mechanism today; a future `metrics-export` blueprint plus a future `tracing` blueprint is the natural evolution.
+
+## What a good outcome looks like
+
+A project applies the observability-essentials blueprint on a fresh tree, declares its readiness dependency set (payments-provider, primary-store, sms-gateway) in configuration, declares its public component list (Payments, Notifications, Data) in configuration, wires TAC-801 through TAC-804 into project-authored FBSes, and lands on a deployed application where:
+
+- The orchestrator hits /healthz on the request-traffic listener every N seconds; every hit gets 200 with the JSON body inside a millisecond budget; a stuck process is restarted within N seconds of wedging.
+- The load balancer hits /readyz on the request-traffic listener every N seconds; a healthy replica gets 200 and stays in rotation, a replica whose declared payments-provider dependency has gone offline gets 503 and is pulled from rotation without restart. The replica comes back to rotation when the dependency's cached state returns to pass.
+- An external customer visits /status without a login, sees the three declared components (Payments: operational, Notifications: degraded, Data: operational) with the current state enum values as data attributes, sees the active incident notice above the component list with its title, body, severity, startedAt and componentIds fields, and does not see any hostname, replica id, database identifier, queue name, internal URL, build hash, request count, latency number, error rate, queue depth, or readiness dependency name anywhere on the page.
+- Every notification the application attempts records exactly one outcome record on the durable sink with the notificationId, channel, recipient, outcome, attemptedAt, and (on failure) errorCode fields; the operator queries the sink by recipient identifier and time window and gets the outcome records that match; a recipient with no attempts in the window returns an empty result set.
+- A downstream partial outage (a payments-provider that has gone slow) turns the readiness cached state for that dependency to fail; readiness probes return 503 within the readiness evaluation budget; liveness probes continue to return 200 within the tighter liveness budget; the load balancer pulls the affected replicas from rotation; the orchestrator does not restart them; the payments-provider recovers, the background evaluator refreshes the cached state to pass, readiness returns 200, and the replicas re-enter rotation without human intervention.
+
+## Operator decisions that remain open after apply
+
+- The liveness path, the readiness path, and the status page path defaults are /healthz, /readyz, and /status; the project overrides them at boot for compliance with a particular orchestrator convention or platform mandate.
+- The readiness dependency set (which downstream deps a failure of makes this replica unfit to serve). Blueprint owns the strict-any-fail semantics and the declaration shape; project owns the concrete dep list.
+- The public component list on the status page (name and order). Blueprint owns the vocabulary shape and the state enum; project owns the components themselves and the mapping from internal dep state to public component state.
+- The active incident notice authoring workflow (how the operator posts a notice, where the notice store lives, who has permission to post). Blueprint owns the notice field set and the render contract; project owns the write path.
+- The background dep-health evaluator cadence and per-dep evaluation budget. Blueprint owns the pattern (cached state, background evaluator, per-dep budget); project owns the concrete cadence and per-dep budget values.
+- The notification outcome sink substrate (composing with persistence: a facade verb on that store; standalone: a project-authored durable writer). Blueprint owns the record shape and the enums; project owns the substrate.
+- The auth-exempt list (the three paths the blueprint declares; the project decides whether any additional paths should be exempt or whether the exempt list should be stricter).
+- Whether to publish the readiness probe path (and its body) to third-party monitoring integrations. Blueprint owns the body shape stability guarantee; project owns the publish decision.
+
+## Cost-honesty paragraph
+
+Shipping this doc set costs the project the following. Every request path pays two probe endpoints on the same listener as request traffic; both handlers are trivial but still consume a small share of the router's dispatch cost. The background dep-health evaluator runs on its own cadence for the process lifetime; a project with N declared dependencies pays N per-dep evaluations per cadence, and each evaluation is a project-authored function that can spend as much time as it likes inside its own budget. The public status page is a first-class HTTP surface the project owns forever: renaming a declared component is a public-contract change; adding a new component is a public-contract change; the fixed state enum and fixed notice severity enum are commitments. The notification outcome sink adds a durable write per notification attempt; a project that sends millions of notifications a day pays proportionately, and the durable substrate has to handle the write rate. The three auth-exempt paths are a security invariant the project maintains across every auth middleware refactor. In return, the project gets: a restart signal decoupled from downstream health, a rotation signal that names which dep failed, a public surface that answers 'is this up' without human involvement, and an answer to 'did the customer get the notification' that is a query not an escalation.

package/blueprints/observability-probe-endpoints/README.md

@@ -0,0 +1,53 @@
+# Observability probe endpoints blueprint (v1.0.0)
+
+The tenth content blueprint on the rcf-build-lite blueprint mechanism, and the second in the `observability` category, sibling to the shipped `observability-essentials`. Scope: a health probe interface derived from an operator-declared target integration profile (`kubernetes`, `loadBalancer`, `uptimeMonitor`, `systemd`, `dockerHealthcheck`, `reverseProxy`, plus a `custom:<name>` slot). Each profile fixes the probe transport, path or command surface, response contract, and semantic distinction between liveness and readiness for the supervisor at hand. Kubernetes is the shipped default (HTTPGet `/live` and `/ready` on the request-traffic listener); every HTTP profile ships with a `probeListener.separatePort` opt-in for probe-traffic isolation from user traffic. Response contracts are minimal by construction; the profile validator refuses any override that would add a field beyond the enumerated set. Targeted at rcf-lite projects that must integrate with a specific EXTERNAL supervising system whose conventions drive the probe wire shape; not targeted at the self-supervised all-in-one observability case (observability-essentials owns that).
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/observability-probe-endpoints
+```
+
+Phase 1 resolves local path sources only; registry and git-ref resolution is a mechanism follow-up. Apply is idempotent; `rcf define blueprint list` shows the applied entry grouped under the `observability` category; `rcf define blueprint remove observability-probe-endpoints` cleanly removes an unreferenced application.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version, category `observability`, and the 25 contributions with scope/topic on the two global ADRs |
+| Doc set | `contributions/` | 8 REQs, 8 USs (24 ACs), 4 TACs, 5 ADRs, all schema-valid and namespaced (`observability-probe-endpoints-REQ-001` prefix family; `ADR-1501-observability-probe-endpoints-health-probes` suffix family) |
+| Kubernetes probe sample | `assets/kubernetes/podspec-probes.md` | The exact `livenessProbe` and `readinessProbe` fragments for a Kubernetes podspec that consumes the shipped default HTTPGet `/live` and `/ready` surface, with placeholder container name and port |
+| Kubernetes separate-port sample | `assets/kubernetes/podspec-probes-separate-port.md` | The podspec fragment for the separate-port topology with a dedicated `containerPort` for probes that is not published on the `Service` |
+| Load-balancer health-check sample | `assets/load-balancer/health-check-config.md` | A vendor-neutral load-balancer target-group health-check configuration illustrating the single-endpoint `/health` GET with status-code-only response |
+| systemd unit sample | `assets/systemd/notify-service.md` | A `Type=notify` systemd unit fragment illustrating the `sd_notify(READY=1)` and `WATCHDOG=1` posture |
+| Docker HEALTHCHECK sample | `assets/docker/dockerfile-healthcheck.md` | A Dockerfile fragment with `HEALTHCHECK CMD` invoking the profile's exec-transport entry point |
+| Uptime monitor URL sample | `assets/uptime-monitor/monitor-config.md` | A vendor-neutral uptime-monitor configuration example for the single-URL check pattern |
+| Guide | `guide/observability-probe-endpoints.md` | Operator-facing: when to use it, when not, boundary with observability-essentials, what stays your call, promotion signals |
+| Coordination vocabulary | `docs/topics.md` | The two global-topic strings this blueprint contributes and the shared id band registry (twelve shipped or in-flight blueprints including this one) |
+
+The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
+
+## What it contributes, and what it deliberately does not
+
+Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files (ratified decision 5) and no code.
+
+No FBS contributions, as a matter of principle (ratified policy 2026-08-19): FBSs are the work of the implementing agent, not the blueprint; project constraints have to be applied at the time of creation. The blueprint contributes the WHAT (the elicitation surface, the six shipped profile contracts, the two-listener topology option, the auth-exempt-list emission, the response-contract secrecy rule, the profile-swap-is-config invariant); the implementing agent derives the HOW-tasks (FBS) in the host project, where the ACs contributed here get picked up by the project's own build sequencing.
+
+Deliberately not contributed: a public status page (observability-essentials owns `statusPageContract` for that audience); a notification outcome sink (observability-essentials owns that); an authenticated operator dashboard for granular internal state (project-authored on top of the readiness predicate); a metrics-export surface (a future `metrics-export` blueprint composes alongside); a distributed-tracing surface (a future `tracing` blueprint composes alongside); a log-shipping surface (application-api-rest's `logging` topic governs the wire-log shape of the HTTP tier); the readiness predicate implementation itself (project-authored; the blueprint fixes the boundary and each profile's default aggregation rule, not the per-dependency check code); the auth middleware installer (project-authored; the blueprint emits an exact-match exempt list the installer consumes); the vendor-CLI or client-library binding for any supervisor beyond the profile contract (project-authored inside a `custom:<name>` profile).
+
+## The two global decisions
+
+ADR-1501-observability-probe-endpoints-health-probes ships `scope: global` on topic `healthProbes`. This is the project's health probe interface: elicited from the target integration profile, materialised by the profile-resolver into a frozen object that drives every downstream binding. A composing blueprint that holds a different opinion on the health probe interface (observability-essentials's self-supervised two-endpoint HTTP JSON floor is the shipped example; a future metrics-probe hybrid or a health-protocol variant would compose here too) conflicts by design.
+
+ADR-1502-observability-probe-endpoints-readiness-semantics ships `scope: global` on topic `readinessSemantics`. This is the project's readiness aggregation and cadence: elicited per profile so the shape and the flip window follow what the supervising system reads. A composing blueprint that holds a different opinion on readiness semantics (observability-essentials's strict-any-fail-over-declared-deps as the ONE project-wide rule is the shipped example) conflicts by design.
+
+Both ADRs conflict with observability-essentials on the same two topic strings on purpose. See `docs/topics.md` for the exact strings, the four documented resolution paths per conflict, the boundary with observability-essentials's `statusPageContract` (which this blueprint does not touch), and the AC id band allocation (observability-probe-endpoints owns 14101-14899, ADR/TAC suffix block 15xx).
+
+## Quality bar
+
+The probe surface always follows the operator-declared target integration profile; a missing or unrecognised declaration refuses boot with a stable-coded error naming the field. The Kubernetes profile is the shipped default; a bare apply exhibits HTTPGet `/live` and `/ready` on the request-traffic listener with the `{"status":"pass"|"fail"}` body shape and no operator configuration. Each of the six shipped profiles resolves to a config object whose transport, path (or command/notify equivalent), response contract, and semantic model are all present; a partial profile is refused at boot. Every HTTP profile carries a `probeListener.separatePort` opt-in; when set, probe handlers bind to a dedicated listener that serves only the resolved probe path set and no other routes; when unset, probe handlers bind to the user-traffic listener. Response contracts are minimal by construction: HTTP profiles that consume status-only carry content-length zero on every response; HTTP profiles that consume a body emit exactly the enumerated field set (`{"status":"pass"|"fail"}` for Kubernetes and nothing more); the profile validator refuses any override that would add a field beyond the enumerated set. No dependency name, environment name, hostname, replica id, build hash, or commit sha ever appears on any external-visible probe response. The auth-exempt list emitted by the topology component is exact-match scoped to the resolved probe path set on the resolved listener; a wildcard or prefix matcher is refused. Switching profiles is a configuration change; the source tree carries no per-profile conditional outside the profile modules and the profile-resolver. Every bar is carried by ACs in the doc set, not by this README.
+
+## Known mechanism-reach gaps
+
+- **Custom-profile contract adherence.** Projects that author a `custom:<name>` profile against the profile contract are expected to satisfy the same transport/paths/responseContract/semanticModel shape the shipped profiles do; the profile contract validator (TAC-1501) refuses a partial profile at boot, which is where the mechanism reach lands. What the validator cannot compel is that a project-authored custom profile's response shape is minimal in the AC-14105 and AC-14106 sense (a custom profile could in principle enumerate a rich field set the validator would accept as complete). Recorded here rather than smuggled in as an AC that would only apply to the shipped profiles. Promotion signal: a `custom-profile-shape-lint` addition to the profile contract validator that enforces the minimalism rule per field-set-size heuristic (harder than it sounds; some legitimate custom profiles do have wider fields); or a project-side grep gate. Project-side workaround until then: reviewers of a `custom:<name>` profile eyeball the enumerated field set against the pattern the shipped six carry.
+- **Kubernetes gRPC probe transport.** The `kubernetes` profile ships HTTPGet and TCPSocket transports (via TAC-1504's tcpAdapter selection) but not gRPC. A project on a gRPC-only mesh that wants the standard gRPC health protocol supersedes ADR-1503 with a project-level ADR selecting the gRPC transport, or authors a `custom:kubernetes-grpc` profile. Promotion signal: a shipped gRPC-transport handler in a v1.1 pass if enough rcf-lite projects reach for it. Project-side workaround: the `custom:<name>` slot is the mechanism escape hatch.

package/blueprints/observability-probe-endpoints/assets/docker/dockerfile-healthcheck.md

@@ -0,0 +1,19 @@
+# Docker HEALTHCHECK
+
+Reference for a Dockerfile fragment consuming the `dockerHealthcheck` profile's exec transport. The `HEALTHCHECK CMD` invokes the entry point the profile exposes; the exit code IS the probe answer.
+
+```dockerfile
+# ... application build stages omitted ...
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD /usr/local/bin/<service-binary> --healthcheck || exit 1
+```
+
+Notes.
+
+- The `--healthcheck` flag on the service binary is the profile's exec entry point (TAC-1504's `execAdapter` exposes `runHealthcheck`); it reads the readiness predicate and exits 0 on pass, non-zero on fail.
+- `--interval`, `--timeout`, `--start-period`, `--retries` are Docker HEALTHCHECK defaults; tune per the container orchestrator's expectations.
+- `docker inspect` and Docker Compose's `depends_on: condition: service_healthy` consume the resulting health status.
+- No HTTP probe listener is opened by the process when the `dockerHealthcheck` profile is selected (AC-14105-3).
+
+Reference: docs.docker.com/reference/dockerfile/#healthcheck for the HEALTHCHECK instruction reference.

package/blueprints/observability-probe-endpoints/assets/kubernetes/podspec-probes-separate-port.md

@@ -0,0 +1,54 @@
+# Kubernetes probe podspec (separate-port topology)
+
+Reference fragment for a Kubernetes podspec that consumes the `kubernetes` profile with `probeListener.separatePort: 9091`: probes bind to a dedicated container port that is NOT published on the `Service`; only the traffic port is public. The kubelet reaches the probe port on the pod network.
+
+```yaml
+containers:
+  - name: <container-name>
+    image: <image-ref>
+    ports:
+      - name: http
+        containerPort: 8080
+      - name: probe
+        containerPort: 9091
+    livenessProbe:
+      httpGet:
+        path: /live
+        port: probe
+      initialDelaySeconds: 5
+      periodSeconds: 10
+      timeoutSeconds: 1
+      failureThreshold: 3
+    readinessProbe:
+      httpGet:
+        path: /ready
+        port: probe
+      initialDelaySeconds: 2
+      periodSeconds: 5
+      timeoutSeconds: 1
+      failureThreshold: 3
+```
+
+And the matching `Service` that publishes only the traffic port:
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: <service-name>
+spec:
+  selector:
+    app: <selector-label>
+  ports:
+    - name: http
+      port: 80
+      targetPort: http
+```
+
+Notes.
+
+- The probe port (`9091` here) appears on the pod but not on the `Service`; the probe surface is reachable to the kubelet on the pod network and not from cluster consumers of the `Service`.
+- The separate probe listener binds only the profile's resolved probe path set; any other path on port 9091 returns not-found (AC-14104-2).
+- Reachability equivalence between probes and user traffic is traded for probe-traffic isolation; the fused topology is the default and matches observability-essentials's posture for the case where the trade goes the other way.
+
+Reference: kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes for probe field references and the pattern of using a distinct container port for probes.

package/blueprints/observability-probe-endpoints/assets/kubernetes/podspec-probes.md

@@ -0,0 +1,36 @@
+# Kubernetes probe podspec (fused topology default)
+
+Reference fragment for a Kubernetes podspec that consumes the shipped `kubernetes` profile default: HTTPGet `/live` and `/ready` on the container's request-traffic port. The port name below assumes the container publishes its user-traffic listener on a named port `http`; substitute the project's chosen name.
+
+```yaml
+containers:
+  - name: <container-name>
+    image: <image-ref>
+    ports:
+      - name: http
+        containerPort: 8080
+    livenessProbe:
+      httpGet:
+        path: /live
+        port: http
+      initialDelaySeconds: 5
+      periodSeconds: 10
+      timeoutSeconds: 1
+      failureThreshold: 3
+    readinessProbe:
+      httpGet:
+        path: /ready
+        port: http
+      initialDelaySeconds: 2
+      periodSeconds: 5
+      timeoutSeconds: 1
+      failureThreshold: 3
+```
+
+Notes.
+
+- The paths `/live` and `/ready` match the shipped `kubernetes` profile default. Override in the profile with `probeInterface.options.kubernetes.paths.{liveness,readiness}` and adjust these fragments to match.
+- `initialDelaySeconds`, `periodSeconds`, `timeoutSeconds`, and `failureThreshold` are project defaults; tune per the supervising cluster's expectations.
+- The response contract is `{"status":"pass"}` on pass and `{"status":"fail"}` on fail with status codes 200 and 503; the kubelet reads only the status code. The body is present for operator triage under `kubectl describe pod` and equivalent introspection paths, and stays minimal by construction (ADR-1505).
+
+Reference: kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes for the probe reference; kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#httpgetaction-v1-core for the HTTPGetAction field reference.

package/blueprints/observability-probe-endpoints/assets/load-balancer/health-check-config.md

@@ -0,0 +1,23 @@
+# Load balancer health check configuration
+
+Reference for a vendor-neutral load-balancer target-group health check consuming the `loadBalancer` profile's single HTTP GET at `/health` with status-code-only response. Field names below reflect the shape most application-load-balancer products expose; substitute the exact field names of the vendor at hand.
+
+```
+protocol: HTTP
+port: <traffic-port>
+path: /health
+matcher: 200
+interval: 15 seconds
+timeout: 5 seconds
+healthyThreshold: 2
+unhealthyThreshold: 2
+```
+
+Notes.
+
+- The `path` `/health` matches the shipped `loadBalancer` profile default. Override with `probeInterface.options.loadBalancer.path`.
+- The `matcher: 200` reflects the profile's response contract: pass is status code 200 with content-length zero; fail is status code 503 with content-length zero. The LB reads only the status code.
+- `interval`, `timeout`, `healthyThreshold`, `unhealthyThreshold` are common defaults; tune per the LB's expectations and the readiness evaluator cadence the project chose (a shorter LB interval than the evaluator cadence sees stale answers; a longer LB interval flips slower than the underlying state).
+- The response body is empty. A body-inspecting matcher against this profile is a project misconfiguration; the profile refuses at boot any override adding a body field (AC-14106-3).
+
+Reference: general load-balancer health-check documentation across major vendors is consistent on the single-endpoint status-code-only shape (AWS ELB/ALB target-group health checks, GCP load balancer health checks, Azure Load Balancer health probes, Cloudflare Load Balancer monitors); consult the specific vendor's docs for exact field names.

package/blueprints/observability-probe-endpoints/assets/systemd/notify-service.md

@@ -0,0 +1,30 @@
+# systemd Type=notify unit
+
+Reference for a systemd unit consuming the `systemd` profile's `sd_notify` transport. The unit sits on `Type=notify` and delegates the ready-and-watchdog protocol to the process itself.
+
+```ini
+[Unit]
+Description=<service description>
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=notify
+NotifyAccess=main
+ExecStart=/usr/local/bin/<service-binary>
+Restart=on-failure
+WatchdogSec=30s
+TimeoutStartSec=60s
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Notes.
+
+- `Type=notify` blocks systemd's start on the process reaching its ready state; the profile's non-HTTP adapter (TAC-1504) emits `sd_notify(READY=1)` after boot to satisfy that.
+- `WatchdogSec=30s` declares the watchdog cadence; the profile's adapter then emits `sd_notify(WATCHDOG=1)` at (at most) that cadence for the process lifetime. A missed cadence causes systemd to terminate and restart the process per the unit's restart policy.
+- `NotifyAccess=main` restricts the notify socket to the main process, matching the profile's single-adapter posture.
+- No HTTP probe listener is opened for a process running only the `systemd` profile (AC-14105-3 for the analogous `dockerHealthcheck` invariant).
+
+Reference: freedesktop.org/software/systemd/man/sd_notify.html for the notify protocol; freedesktop.org/software/systemd/man/systemd.service.html for the unit-file field reference.

package/blueprints/observability-probe-endpoints/assets/uptime-monitor/monitor-config.md

@@ -0,0 +1,22 @@
+# Uptime monitor configuration
+
+Reference for a vendor-neutral uptime-monitor configuration consuming the `uptimeMonitor` profile's single URL check. Uptime monitors probe a public URL from external vantage points and page the operator when the check fails against a threshold. Field names below reflect the shape most uptime-monitor products expose.
+
+```
+url: https://<public-hostname>/health
+method: GET
+expectedStatus: 200
+interval: 60 seconds
+timeout: 10 seconds
+regions: <one-or-more-vantage-points>
+alertOn: <threshold-of-consecutive-failures>
+```
+
+Notes.
+
+- The `url` path `/health` matches the shipped `uptimeMonitor` profile default (same path as `loadBalancer`; the difference sits in the flip cadence per ADR-1502, not in the path). Override with `probeInterface.options.uptimeMonitor.path`.
+- The profile's response contract is status-code-only with content-length zero on every response; the monitor reads only the status code.
+- `interval`, `timeout`, and `alertOn` are usually monitor-side tunables; the profile keeps its readiness evaluator cadence set for a stable answer over the monitor's flap window so a transient dependency blip does not page.
+- Uptime monitors that page on body content are outside this profile's scope; a project on such a monitor authors a `custom:<name>` profile or supersedes ADR-1505.
+
+Reference: general uptime-monitor documentation across vendors is consistent on the single-URL status-code-plus-optional-body-string shape (Pingdom, UptimeRobot, BetterStack, Datadog Synthetics, StatusCake); consult the specific vendor's docs for exact field names.

package/blueprints/observability-probe-endpoints/blueprint.json

@@ -0,0 +1,44 @@
+{
+  "slug": "observability-probe-endpoints",
+  "version": "1.0.0",
+  "category": "observability",
+  "contributions": [
+    { "id": "observability-probe-endpoints-REQ-001", "kind": "req", "path": "requirements/observability-probe-endpoints-req-001.json" },
+    { "id": "observability-probe-endpoints-REQ-002", "kind": "req", "path": "requirements/observability-probe-endpoints-req-002.json" },
+    { "id": "observability-probe-endpoints-REQ-003", "kind": "req", "path": "requirements/observability-probe-endpoints-req-003.json" },
+    { "id": "observability-probe-endpoints-REQ-004", "kind": "req", "path": "requirements/observability-probe-endpoints-req-004.json" },
+    { "id": "observability-probe-endpoints-REQ-005", "kind": "req", "path": "requirements/observability-probe-endpoints-req-005.json" },
+    { "id": "observability-probe-endpoints-REQ-006", "kind": "req", "path": "requirements/observability-probe-endpoints-req-006.json" },
+    { "id": "observability-probe-endpoints-REQ-007", "kind": "req", "path": "requirements/observability-probe-endpoints-req-007.json" },
+    { "id": "observability-probe-endpoints-REQ-008", "kind": "req", "path": "requirements/observability-probe-endpoints-req-008.json" },
+    { "id": "observability-probe-endpoints-US-14101", "kind": "us", "path": "user-stories/observability-probe-endpoints-us-14101.json" },
+    { "id": "observability-probe-endpoints-US-14102", "kind": "us", "path": "user-stories/observability-probe-endpoints-us-14102.json" },
+    { "id": "observability-probe-endpoints-US-14103", "kind": "us", "path": "user-stories/observability-probe-endpoints-us-14103.json" },
+    { "id": "observability-probe-endpoints-US-14104", "kind": "us", "path": "user-stories/observability-probe-endpoints-us-14104.json" },
+    { "id": "observability-probe-endpoints-US-14105", "kind": "us", "path": "user-stories/observability-probe-endpoints-us-14105.json" },
+    { "id": "observability-probe-endpoints-US-14106", "kind": "us", "path": "user-stories/observability-probe-endpoints-us-14106.json" },
+    { "id": "observability-probe-endpoints-US-14107", "kind": "us", "path": "user-stories/observability-probe-endpoints-us-14107.json" },
+    { "id": "observability-probe-endpoints-US-14108", "kind": "us", "path": "user-stories/observability-probe-endpoints-us-14108.json" },
+    { "id": "TAC-1501-observability-probe-endpoints-profile-resolver", "kind": "tac", "path": "tacs/tac-1501-observability-probe-endpoints-profile-resolver.json" },
+    { "id": "TAC-1502-observability-probe-endpoints-handler-set", "kind": "tac", "path": "tacs/tac-1502-observability-probe-endpoints-handler-set.json" },
+    { "id": "TAC-1503-observability-probe-endpoints-listener-topology", "kind": "tac", "path": "tacs/tac-1503-observability-probe-endpoints-listener-topology.json" },
+    { "id": "TAC-1504-observability-probe-endpoints-non-http-adapters", "kind": "tac", "path": "tacs/tac-1504-observability-probe-endpoints-non-http-adapters.json" },
+    {
+      "id": "ADR-1501-observability-probe-endpoints-health-probes",
+      "kind": "adr",
+      "path": "adrs/adr-1501-observability-probe-endpoints-health-probes.json",
+      "scope": "global",
+      "topic": "healthProbes"
+    },
+    {
+      "id": "ADR-1502-observability-probe-endpoints-readiness-semantics",
+      "kind": "adr",
+      "path": "adrs/adr-1502-observability-probe-endpoints-readiness-semantics.json",
+      "scope": "global",
+      "topic": "readinessSemantics"
+    },
+    { "id": "ADR-1503-observability-probe-endpoints-kubernetes-default", "kind": "adr", "path": "adrs/adr-1503-observability-probe-endpoints-kubernetes-default.json" },
+    { "id": "ADR-1504-observability-probe-endpoints-separate-port-option", "kind": "adr", "path": "adrs/adr-1504-observability-probe-endpoints-separate-port-option.json" },
+    { "id": "ADR-1505-observability-probe-endpoints-external-response-secrecy", "kind": "adr", "path": "adrs/adr-1505-observability-probe-endpoints-external-response-secrecy.json" }
+  ]
+}

package/blueprints/observability-probe-endpoints/contributions/adrs/adr-1501-observability-probe-endpoints-health-probes.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-1501-observability-probe-endpoints-health-probes",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "The health probe interface is elicited from the operator-declared target integration profile; the probe transport, path, response contract, and semantics fall out of that one declaration",
+  "context": "External supervisors probing a service each carry their own conventions for what a probe looks like and what the answer means. A Kubernetes kubelet expects an HTTPGet, TCPSocket, Exec, or gRPC probe of a specific shape at a container-declared path or port, and reads a two-probe split (liveness vs readiness) as a first-class model. An application load balancer expects one HTTP GET with the answer in the status code and no body semantics beyond that. An uptime monitor expects a URL that returns 200 or 5xx. A systemd unit under `Type=notify` blocks on `sd_notify(READY=1)` and then watches for periodic `WATCHDOG=1` notifications, not synchronous probes. A Docker HEALTHCHECK is an exec command whose exit code is the answer. A service that ships one fixed probe shape is correct for one supervisor and wrong for the others; a service that ships adapter shims per deployment context adds surface area everywhere and never quite matches any convention. The observability-essentials sibling blueprint holds a legitimate different opinion for the case where the service designs its own observability floor without a specific external supervisor's conventions in view: two HTTP JSON probes on the request-traffic listener with a stable body shape, fine when the service is its own supervisor's audience. This blueprint targets the other case: the supervisor's conventions come first and the service materialises the probe surface for them.",
+  "decision": "The health probe interface is derived from an operator-declared target integration profile. The blueprint ships six profiles: `kubernetes`, `loadBalancer`, `uptimeMonitor`, `systemd`, `dockerHealthcheck`, `reverseProxy`, plus a `custom:<name>` slot for project-authored profiles. Each profile fixes the probe transport (HTTP GET, TCP socket accept, exec command, supervisor notify), the probe path or command surface, the response contract (status code only, minimal JSON body of the shape `{\"status\":\"pass\"|\"fail\"}`, exit code, notify call sequence, or connect-and-close), and the semantic distinction between liveness and readiness (two-endpoint for Kubernetes, single-signal for load balancers and uptime monitors, notify-plus-watchdog for systemd, one-command for Docker HEALTHCHECK). The Kubernetes profile is the shipped default (see ADR-1503). Every HTTP profile carries a `probeListener.separatePort` option for probe traffic isolation (see ADR-1504). The profile object drives every wiring choice; nothing in the process reaches for a probe transport, path, or response outside the profile.",
+  "consequences": "The probe surface always matches the supervisor conventions the service actually runs under, and a change of supervising system is a configuration change (see REQ-008 and US-14108). Composing this blueprint with the observability-essentials sibling on the same project fires a `healthProbes` global-topic conflict on purpose, because the two blueprints answer different questions about what the probes are for: essentials commits to a self-supervised HTTP JSON contract on the request-traffic listener as the project-wide floor; this blueprint commits to an elicit-and-adapt model whose shape follows the external supervisor. The expected resolution is one project-level ADR that either (a) accepts this blueprint's elicit-and-adapt model when the service must integrate with a specific external supervisor's conventions, (b) accepts observability-essentials's self-supervised fused model when the project designs its own probes without a specific external supervisor's conventions in view, or (c) authors a project-specific hybrid that names both surfaces (e.g., an internal essentials-shaped surface for one audience and a profile-shaped external surface for the supervising system) with explicit boundaries.",
+  "alternativesConsidered": [
+    {
+      "name": "Fold the elicit-and-adapt shape into observability-essentials as a v2 addition",
+      "summary": "Extend observability-essentials's ADR-801 to accept a profile-name parameter and let the essentials blueprint carry both the self-supervised default and the external-integration variants inside one contribution set.",
+      "reasonNotChosen": "The essentials blueprint's identity is the all-in-one basic observability floor (probes plus public status page plus notification outcome sink); merging the elicit-and-adapt shape into it either dilutes that identity or forces the essentials all-in-one bundle onto projects that only wanted the external-integration probe surface. Keeping the two blueprints on separate rows honours the boundary the round-2 canon named and lets each carry the right defaults for its audience."
+    },
+    {
+      "name": "Ship one blueprint per external supervisor",
+      "summary": "Author `observability-probes-kubernetes`, `observability-probes-load-balancer`, `observability-probes-uptime-monitor`, `observability-probes-systemd`, `observability-probes-docker-healthcheck` as five distinct blueprints, one per supervisor family.",
+      "reasonNotChosen": "The elicitation surface is small and the profile contract is shared across supervisors; splitting into five blueprints multiplies the maintenance load (five README, five topics.md, five id band allocations, five conflict rows against observability-essentials) without giving the operator anything they cannot express by naming the profile at boot. The single-blueprint form also lets a project that legitimately runs under two supervisors (a Kubernetes deployment fronted by a load balancer whose LB health check hits a different path than the kubelet probes) declare a custom profile that composes the two shapes with one apply."
+    },
+    {
+      "name": "Kubernetes-only blueprint",
+      "summary": "Ship `observability-probes-kubernetes` alone and leave the other supervisors to project-side work or future blueprints.",
+      "reasonNotChosen": "The round-2 canon explicitly named the identity as `observability-probe-endpoints` (probe endpoints elicited per deployment type; k8s /live /ready default; separate-port/separate-server option), not `observability-probes-kubernetes`. The elicitation is the point; the Kubernetes default is one honoured convention among several the same profile-contract shape covers cleanly."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/adrs/adr-1502-observability-probe-endpoints-readiness-semantics.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-1502-observability-probe-endpoints-readiness-semantics",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Readiness semantics are declared per target integration profile; the aggregation rule and the meaning of 'not ready' belong to the operator's mapping onto the supervising system's interpretation",
+  "context": "Readiness answers a question the supervising system will act on. Kubernetes pulls a pod out of the Service endpoint list; a load balancer stops routing new requests to a target; an uptime monitor pages an operator; a Docker HEALTHCHECK failure marks the container unhealthy for other services to react to. What 'not ready' means, how per-dependency states aggregate into the answer, and how quickly the answer needs to flip are shaped by which supervisor is doing the interpretation. The observability-essentials sibling blueprint fixes one legitimate answer as the project-wide rule: strict-any-fail over an explicit boot-time-declared dependency set, evaluated against per-dependency cached state maintained by a background evaluator on its own cadence. That is a sensible default when the project owns readiness end-to-end and wants a single reviewable declaration. It is not the right default when the supervising system's interpretation drives the semantics: a load balancer that will pull the target aggressively wants a different aggregation from a kubelet that will only skip the pod for the next request-routing pass; an uptime monitor's threshold-based paging logic wants a different flip cadence from a synchronous supervisor's per-hit answer.",
+  "decision": "Readiness semantics are declared per target integration profile. The blueprint fixes the SHAPE of the readiness predicate contract (a synchronous function `() -> 'pass' | 'fail'` that reads state a project-supplied evaluator maintains on its own cadence and is called from the resolved probe handler) but each profile carries its own default for the aggregation rule and the evaluator cadence. Kubernetes profile default: strict-any-fail over the operator-declared dependency set, cached at the evaluator cadence (aligned with the Kubernetes community convention documented at kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes). Load balancer profile default: strict-any-fail with a tighter evaluator cadence so the LB observes the flip within its own health-check interval budget. Uptime monitor profile: the same predicate wired to a longer effective flip window because the monitor's threshold-based paging usually wants a stable answer rather than a per-hit flap. systemd profile: readiness is announced once via `sd_notify(READY=1)` and then the process holds ready state until watchdog cadence catches a wedge. Docker HEALTHCHECK: one exit-code answer per invocation, with the aggregation rule the profile default carries. Each profile documents its aggregation choice; a project supersedes at the profile-options layer without touching the readiness predicate contract.",
+  "consequences": "Composing this blueprint with observability-essentials on the same project fires a `readinessSemantics` global-topic conflict on purpose, because the two blueprints answer different questions. Essentials commits to strict-any-fail-over-declared-deps as the ONE project-wide semantics. This blueprint commits to per-profile semantics where the aggregation choice belongs to the operator's mapping onto the supervising system's interpretation. The expected resolution is one project-level ADR that either (a) commits to the fused observability-essentials rule when the project owns readiness end-to-end with a single supervisor, (b) commits to the elicit-per-profile rule when the readiness meaning is shaped by the specific supervising system, or (c) authors a project-specific hybrid where different surfaces answer to different semantics with explicit boundaries.",
+  "alternativesConsidered": [
+    {
+      "name": "Adopt the observability-essentials strict-any-fail rule wholesale",
+      "summary": "Fix the readiness aggregation across every profile to strict-any-fail over the declared dependency set, matching the essentials sibling.",
+      "reasonNotChosen": "Collapses the reason this blueprint exists. The point of the elicit-and-adapt identity is that different supervisors read readiness differently; forcing one aggregation across every profile hides that difference from the operator and re-invents the problem observability-essentials's fused rule was correctly optimising for a narrower case."
+    },
+    {
+      "name": "Leave readiness entirely to project code",
+      "summary": "Ship only the predicate-interface boundary and refuse to name defaults per profile.",
+      "reasonNotChosen": "Would produce a blueprint that specifies interfaces without helping operators reach a working state; the round-2 identity is 'a service correctly probeable by the external system that supervises it', not 'a service that documents its own interface and expects the operator to bring the semantics'. Naming per-profile defaults is where the blueprint earns its keep."
+    },
+    {
+      "name": "Synchronous per-probe evaluation with no cached-state pattern",
+      "summary": "Every probe hit evaluates every declared dependency with a real network call from inside the probe handler.",
+      "reasonNotChosen": "Turns downstream latency into probe latency; a slow dependency causes the supervisor to time out the probe for reasons unrelated to whether the service could actually serve traffic. The cached-state pattern (the predicate reads state a background evaluator maintains) is a fundamental of the profile contract for that reason; every profile ships with it."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/adrs/adr-1503-observability-probe-endpoints-kubernetes-default.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-1503-observability-probe-endpoints-kubernetes-default",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Kubernetes is the shipped default target integration profile; HTTPGet /live and /ready on the request-traffic listener are its defaults",
+  "context": "One of the shipped profiles has to be the default the process falls back on when the operator does not declare `probeInterface.profile` explicitly. The choice matters because the default is what a project on the shipped configuration exhibits before the operator has spent any time on the observability surface, and because the default shapes the reader's expectation of what the blueprint 'is about'. The round-2 canon selected Kubernetes as the default: `probe endpoints elicited per deployment type; k8s /live + /ready default; separate-port/separate-server option`.",
+  "decision": "The `kubernetes` profile is the shipped default. When the operator does not declare `probeInterface.profile`, the resolver falls back to `kubernetes` with the default paths `/live` (liveness) and `/ready` (readiness), the default `httpGet` transport, the response contract `{\"status\":\"pass\"|\"fail\"}`, the fused listener topology (probes on the user-traffic listener), and the `strict-any-fail-over-declared-deps` readiness aggregation. The paths and the readiness aggregation are overridable at boot via `probeInterface.options.kubernetes.paths` and `probeInterface.options.kubernetes.readinessRule`. The default hits without operator configuration; overriding is a small config change on the same shape.",
+  "consequences": "A project that applies this blueprint and nothing else immediately exhibits a Kubernetes-shaped probe surface at `/live` and `/ready`; the standard `livenessProbe` and `readinessProbe` of shape `httpGet: { path: /live, port: <containerPort> }` and `httpGet: { path: /ready, port: <containerPort> }` in a Kubernetes podspec work without further wiring. The default is scope-local because it is a preference not a contract: the ADR-1501 elicitation model is the global commitment and the Kubernetes profile is one instantiation of it. A project on Docker Compose or on a bare-metal load-balancer setup that runs the shipped default sees `/live` and `/ready` bound instead of `/health` and reads the disagreement as the signal to declare `probeInterface.profile: loadBalancer` at boot.",
+  "alternativesConsidered": [
+    {
+      "name": "Load-balancer profile as the default",
+      "summary": "Ship `loadBalancer` as the default so an unconfigured process answers a single `/health` HTTP GET with status code only.",
+      "reasonNotChosen": "The round-2 canon named Kubernetes as the default explicitly. Load-balancer profile is simpler on the wire (no JSON body, one path) but ships the wrong shape for the majority of the deployments the rcf-lite tier this blueprint targets tends to reach for; Kubernetes has become the default target integration in enough of the industry that shipping it as the default matches the reader's expectation."
+    },
+    {
+      "name": "No default; refuse boot without a declaration",
+      "summary": "The resolver never falls back; the operator must always declare `probeInterface.profile` explicitly.",
+      "reasonNotChosen": "Costs every project one line of configuration for zero value. The whole point of a default is the correct-out-of-the-box case; a project that reaches for the blueprint and does not declare a profile signals 'I want the reasonable default', not 'I want to be nagged for a declaration'. The refusal path stays for the case where the declaration IS present but unrecognised (see US-14101 AC-14101-3)."
+    },
+    {
+      "name": "Auto-detect the deployment context (heuristics on env, hostname, socket paths)",
+      "summary": "Sniff the environment for signals (KUBERNETES_SERVICE_HOST env, /run/systemd/notify socket, Docker cgroups) and pick the profile from what is found.",
+      "reasonNotChosen": "Turns a declaration into a heuristic; heuristics that are usually right are surprising when they are wrong, and the failure mode is a silent binding of the wrong probe shape. The declaration is one field; making the operator name their target integration is a small friction that pays for itself the first time a heuristic would have guessed wrong."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/adrs/adr-1504-observability-probe-endpoints-separate-port-option.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-1504-observability-probe-endpoints-separate-port-option",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "The separate-port listener is an opt-in per-profile option; the fused topology is the default",
+  "context": "Kubernetes convention allows probe handlers to bind to a container port that is not published on the Service, which keeps probe traffic reachable only by the kubelet on the pod network and off the public interface. That property is useful in NAT-and-perimeter-controlled environments where the operator publishes only the request-traffic port outside the pod: an attacker who resolves the public host cannot reach the probe endpoint at all. Load balancers, uptime monitors, and reverse proxies probe the same URL humans browse, so the property does not apply to them. observability-essentials's ADR-801 fixes the fused topology as its answer (probes bind to the request-traffic listener) with a clear rationale: the load balancer probing the traffic port observes the same reachability the traffic will observe. This blueprint offers separate-port as an option instead of a mandate because both properties (reachability equivalence vs. probe-traffic isolation) are legitimate and belong to the operator's choice per environment.",
+  "decision": "Every HTTP-transport profile ships with a `probeListener.separatePort` option that defaults to unset. When unset, probe handlers bind to the user-traffic listener (fused topology, matches observability-essentials's default). When set to a port number, probe handlers bind to a dedicated HTTP listener on that port; the user-traffic listener does not serve probe paths and the separate probe listener serves only the profile's resolved probe path set. No other route on the process binds to the separate probe listener. The option is per-environment overridable; a project's `dev` environment may use fused topology while `live` uses separate-port.",
+  "consequences": "A project on Kubernetes that wants probe isolation from public traffic sets `probeListener.separatePort` and exposes only the traffic port on the Service; a project that wants the load-balancer reachability-equivalence property leaves it unset. Neither answer is the wrong answer; the choice is per environment. The separate-port topology opens a second HTTP listener, which costs a small amount of memory and one more port to think about; the fused topology avoids that at the cost of a second-in-line auth-exempt exception on the user-traffic listener that the project must maintain across every auth middleware refactor.",
+  "alternativesConsidered": [
+    {
+      "name": "Fused topology mandatory",
+      "summary": "Refuse a `probeListener.separatePort` value; probe handlers always bind to the user-traffic listener.",
+      "reasonNotChosen": "Refuses the Kubernetes NAT-and-perimeter-isolation case the operator may genuinely want. observability-essentials made that choice for its own scope (self-supervised project-wide observability); this blueprint's scope (external-integration probing) is exactly where the Kubernetes convention around a dedicated probe port matters most."
+    },
+    {
+      "name": "Separate-port mandatory",
+      "summary": "Refuse the fused topology; probe handlers always bind to a dedicated listener.",
+      "reasonNotChosen": "Loses the reachability-equivalence property (the load balancer probing the traffic port observes the same reachability the traffic will observe). Load-balancer and uptime-monitor profiles legitimately want fused topology; forcing separate-port on them costs a port publication without a benefit."
+    },
+    {
+      "name": "One separate probe listener with multiple auxiliary surfaces (metrics, admin, probes)",
+      "summary": "The separate listener also hosts a project's metrics endpoint and admin endpoints, not only probes.",
+      "reasonNotChosen": "Turns the topology component into a general-purpose admin-listener manager and blurs the scope. Metrics endpoints belong to a future `metrics-export` blueprint that composes alongside this one; admin surfaces belong to an authenticated admin blueprint. The topology component here keeps its scope to the probe path set exactly."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}