rcf-lite 0.12.0 → 0.14.0

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

package/blueprints/observability-probe-endpoints/contributions/adrs/adr-1505-observability-probe-endpoints-external-response-secrecy.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-1505-observability-probe-endpoints-external-response-secrecy",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Every profile's response contract is minimal by construction; internal identifiers never appear on external-visible probe responses",
+  "context": "The probe endpoint is a surface the external supervisor reaches, and on the fused topology it is a surface anyone who resolves the traffic host reaches too. A body that names dependencies, environment identifiers, hostnames, replica ids, build hashes, or commit shas hands a fingerprint to whichever reader arrives. observability-essentials's ADR-804 (probe secrecy) makes the same call in its context. The invariant is the same here; the mechanism is different: instead of author discipline against a stable JSON body shape that must not accumulate fields, this blueprint's response contract is generated per profile from an enumerated field set the profile validator refuses to extend.",
+  "decision": "Every profile's response contract enumerates the fields on the wire. The Kubernetes profile's HTTP JSON body is exactly a one-key object whose only key is `status` and whose value is `pass` or `fail`. The load-balancer, uptime-monitor, and reverse-proxy profile responses carry content-length zero. The systemd profile emits only the supervisor-notify calls its transport requires. The Docker HEALTHCHECK profile emits only an exit code. The profile validator refuses any operator override that adds a field beyond the enumerated set with `PROBE_RESPONSE_FIELD_REFUSED`. Adding a field to the Kubernetes profile's response is a MAJOR version bump on this blueprint; the enumerated set is the wire contract downstream tooling depends on. Operators who want a richer per-dependency triage surface for their own consumption reach for a different blueprint (observability-essentials's readiness probe body carries the per-dep `checks` object for its self-supervised audience) or an authenticated dashboard.",
+  "consequences": "External readers see only the pass or fail answer and the resolved status code; no reconnaissance path opens through the probe body. The invariant is enforced by the profile shape, not by author discipline; a code review does not need to re-check the field set on every touch. Composing this blueprint with a project that wants a richer body ends with a project-level ADR that either supersedes ADR-1505 (accepting the reconnaissance risk explicitly) or supersedes ADR-1501 (accepting observability-essentials's fused shape whose richer body is scoped to a self-supervised audience) rather than a quiet drift into a leaky response.",
+  "alternativesConsidered": [
+    {
+      "name": "Free-form JSON body with author-discipline against leakage",
+      "summary": "The profile's response contract names a starter field set; authors are trusted to keep the body minimal on every touch.",
+      "reasonNotChosen": "Depends on discipline every touch. The observability-essentials sibling records the discipline as an ADR and gets the reader most of the way there; this blueprint targets the case where the external supervisor's surface must not accumulate reconnaissance value, and the load-bearing invariant is 'the profile validator refuses' rather than 'the reviewer refuses'."
+    },
+    {
+      "name": "Cryptographically bound response body with a build-attested signature",
+      "summary": "Every probe response carries a signature the supervisor verifies; internal identifiers appear on the body but are wrapped in signed form.",
+      "reasonNotChosen": "Excess for the surface. Supervisors do not verify probe signatures in the conventions the profile set targets; the added surface increases the leakage class (a signed field is still a leaked field) without paying for itself with a real supervisor verification step. A project that genuinely needs signed probe responses supersedes ADR-1505 with its own signing model."
+    },
+    {
+      "name": "Verbose body under a debug flag",
+      "summary": "The response contract expands to include per-dependency state and hostnames when a `probeInterface.debug: true` boot flag is set.",
+      "reasonNotChosen": "Debug flags in production configurations drift over environment boundaries; a flag set on `dev` that leaks to `live` in a config-merge accident leaks the whole richer surface. The blueprint keeps the minimal-by-construction rule as the only wire contract and points operators at authenticated dashboards or the observability-essentials blueprint's richer self-supervised body for the triage case."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/requirements/observability-probe-endpoints-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-probe-endpoints-REQ-001",
+  "prdId": "PRD-001",
+  "title": "The health probe interface is derived from an operator-declared target integration",
+  "description": "The application exposes health probes shaped for the external system that will probe it. The operator declares a target integration by name (`kubernetes`, `loadBalancer`, `uptimeMonitor`, `systemd`, `dockerHealthcheck`, `reverseProxy`, or a project-authored `custom` profile). The profile fixes the probe transport (HTTP GET, TCP socket accept, exec command, or a supervisor notify call), the probe path or command surface, the response contract, and the port topology defaults. A probe surface not backed by a declared profile is refused at boot with a stable-coded error naming the missing declaration. Nothing in the process wires a probe on its own initiative; the profile drives every binding.",
+  "category": "functional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "External supervisors set the terms of the probe contract, not the service under supervision. A Kubernetes kubelet, an application load balancer, an uptime monitor, and a systemd unit each have their own conventions for what a probe looks like and what the answer means; a service that hard-codes one shape is either wrong for the rest or wraps every deployment in an adapter shim. The elicitation surface names the target integration once, and every wiring choice falls out of that one declaration.",
+  "tags": [
+    "blueprint:observability-probe-endpoints",
+    "category:01-elicitation"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/requirements/observability-probe-endpoints-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-probe-endpoints-REQ-002",
+  "prdId": "PRD-001",
+  "title": "A default Kubernetes profile ships with liveness /live and readiness /ready served over HTTP GET",
+  "description": "When the operator selects the `kubernetes` target integration (the shipped default), the profile wires two HTTP GET probe handlers: a liveness handler at path `/live` and a readiness handler at path `/ready`. Both handlers return HTTP 200 for pass and HTTP 503 for fail. The liveness handler answers strictly on in-process event-loop responsiveness and never depends on any external condition. The readiness handler answers on the operator-declared readiness predicate for the profile (default: strict-any-fail over the declared dependency set). Both paths and the port topology are overridable at boot; the defaults hold when the operator does not override.",
+  "category": "functional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "Kubernetes is the target integration the round-2 canon selected as the default because Kubernetes documents the richest probe contract in the public conventions the industry has settled on: separate liveness and readiness probes, four probe modes (HTTPGet, TCPSocket, Exec, gRPC), configurable path and port, and a well-known interpretation of the answer at the kubelet. Setting the default profile to Kubernetes lets a service stand up correctly under the most common conventions-heavy supervisor without operator configuration; overriding to a different profile is a one-line change.",
+  "tags": [
+    "blueprint:observability-probe-endpoints",
+    "category:02-kubernetes-default"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/requirements/observability-probe-endpoints-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-probe-endpoints-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Each supported target integration profile names its own probe path, response contract, transport, and semantic distinction",
+  "description": "Every profile the blueprint ships names four things: the probe path or command surface (an HTTP path for HTTP profiles, a TCP port for socket profiles, a shell command for exec profiles, a supervisor call for notify profiles); the response contract (HTTP status code range with an optional minimal JSON body for HTTP profiles, connect-and-close for TCP, exit-code zero for exec, one notify call for supervisor); the transport (HTTP GET, TCP SYN, spawned process, or unix socket for supervisor calls); and the semantic distinction between liveness and readiness (two endpoints for Kubernetes; one health signal for load balancers and uptime monitors that do not distinguish; a boot-time readiness notification followed by a periodic watchdog for systemd; a single command answer for Docker HEALTHCHECK). A profile that does not resolve all four is refused at boot with a stable-coded error naming the missing field.",
+  "category": "functional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "The five properties are the elicitation shape. Different external supervisors answer differently on each of them, and the differences are load-bearing: a load balancer that only reads HTTP status has no use for a JSON body; a Kubernetes TCPSocket probe never touches an HTTP path; a systemd unit under Type=notify blocks on a boot notification and then expects periodic watchdog pings, not a synchronous probe. Naming the four properties explicitly per profile is what the elicitation surface exists to do.",
+  "tags": [
+    "blueprint:observability-probe-endpoints",
+    "category:03-profile-shape"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/requirements/observability-probe-endpoints-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-probe-endpoints-REQ-004",
+  "prdId": "PRD-001",
+  "title": "A separate-port listener option is offered per HTTP profile for probe traffic isolation from user traffic",
+  "description": "Every HTTP-transport profile offers a `probeListener.separatePort` option: when unset, probe handlers bind to the same listener that serves user request traffic (the fused topology); when set to a port number, probe handlers bind to a dedicated HTTP listener on that port and the user-traffic listener does not serve probe paths. The separate-port listener binds the profile's probe path set only; no other route is served on that listener. The option is off by default and opt-in per environment.",
+  "category": "functional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "The Kubernetes convention allows probes on a dedicated container port that need not be published on the Service, which keeps probe traffic off the public interface and reachable only by the kubelet on the pod network. Load balancers and uptime monitors that probe the same URL humans browse never need the option. Offering it as an operator choice honours the Kubernetes convention where it applies and stays out of the way everywhere else. The default remains the fused topology because it is simpler, matches the load-balancer probe-the-traffic-port reachability property, and matches the default the observability-essentials sibling assumes.",
+  "tags": [
+    "blueprint:observability-probe-endpoints",
+    "category:04-separate-port"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/requirements/observability-probe-endpoints-req-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-probe-endpoints-REQ-005",
+  "prdId": "PRD-001",
+  "title": "The response contract exposed to the external supervisor matches only what that supervisor consumes",
+  "description": "Every profile's response is exactly what the supervising system reads and nothing more. HTTP-transport profiles that consume status code only (load balancer, uptime monitor, reverse proxy) return an empty response body with the resolved status code. HTTP-transport profiles that consume a body (Kubernetes HTTPGet, where the kubelet ignores body but operators inspect it during triage) return a minimal JSON body of the shape `{ \"status\": \"pass\" }` or `{ \"status\": \"fail\" }` with no additional fields. TCP-transport profiles complete the SYN-ACK handshake on pass and refuse the connection on fail. Exec-transport profiles exit with code 0 on pass and a non-zero code on fail. Supervisor-notify profiles emit exactly the notify calls the supervisor expects (for systemd: `READY=1` at startup, `WATCHDOG=1` on the configured watchdog cadence).",
+  "category": "nonFunctional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "Exposing more than what the supervisor consumes leaks operational surface (dependency names, per-check timings, internal codes) to whichever party can reach the probe endpoint. Load balancers and uptime monitors reach the probe from the public network; a body they never read is a body only the wrong party reads. Kubernetes probes reach from the pod network but the answer is a supervision signal, not a debug surface; richer operator triage sits behind an authenticated dashboard or a separate profile, not on the probe.",
+  "tags": [
+    "blueprint:observability-probe-endpoints",
+    "category:05-response-minimalism"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/requirements/observability-probe-endpoints-req-006.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-probe-endpoints-REQ-006",
+  "prdId": "PRD-001",
+  "title": "No internal identifier is exposed on any external-visible probe response",
+  "description": "The probe response, on every profile that emits a response payload, contains no dependency name, no environment name (dev, staging, live), no hostname, no replica id, no database identifier, no queue name, no internal URL, no build hash, no commit sha, no numeric metric value, no dependency count, no latency measurement, no error rate. The response is bounded to the fields REQ-005 enumerates for the profile and to the resolved status code. A profile that adds any field beyond that set is refused by the profile validator at boot with a stable-coded error naming the offending field.",
+  "category": "security",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "The probe endpoint is the surface the external supervisor reaches; on public HTTP profiles that surface is also reachable by anyone who resolves the traffic host. Fingerprinting a service by its probe body is a documented reconnaissance step; every internal identifier on the response feeds it. The invariant is enforced by the profile shape, not by author discipline: a body richer than pass or fail fails the validator, not code review.",
+  "tags": [
+    "blueprint:observability-probe-endpoints",
+    "category:06-external-secrecy"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/requirements/observability-probe-endpoints-req-007.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-probe-endpoints-REQ-007",
+  "prdId": "PRD-001",
+  "title": "The probe paths are auth-exempt scoped exactly to the resolved probe path set on the resolved listener",
+  "description": "For every HTTP-transport profile, the probe path set the profile resolved (e.g., `/live` and `/ready` for Kubernetes default) is exempt from the project's auth middleware on the listener the profile bound those handlers to. The exemption is scoped by exact path match and by listener, never by prefix. When the fused topology is in effect, the exemption applies on the user-traffic listener for those exact paths only; when the separate-port topology is in effect, the exemption applies on the separate probe listener for those exact paths only and no auth middleware runs on the separate listener because no other route is served there. A path near a probe path but not on the resolved set (e.g., `/ready/next` when `/ready` is the probe) receives the project's normal auth treatment.",
+  "category": "security",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "The probe endpoints must answer without a credential the supervisor cannot present; the exemption is a security invariant, not a convenience. Scoping by exact path stops an inadvertent exemption expanding to a route the exemption never intended to cover. Scoping by listener keeps the fused-topology invariant honest when a project migrates to separate-port later.",
+  "tags": [
+    "blueprint:observability-probe-endpoints",
+    "category:07-auth-exempt"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/requirements/observability-probe-endpoints-req-008.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-probe-endpoints-REQ-008",
+  "prdId": "PRD-001",
+  "title": "A change of target integration profile is a configuration change; the source tree does not re-shape",
+  "description": "Switching the target integration from one profile to another (for example, moving a service from a Kubernetes deployment to a Docker Compose deployment behind a load balancer) is expressed as a change to the operator-declared profile name and its per-profile options. The source tree that binds the profile handlers and the profile-resolver call site do not change; the profile shift takes effect on the next process start. A source-tree change is required only when the operator authors a new custom profile or extends the shipped profile set; existing profiles are switched by configuration alone.",
+  "category": "nonFunctional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "The elicitation surface earns its complexity by making the switch cheap. A project that pays for the resolver plus the handler-set indirection at author time must get a configuration-only migration path in return; otherwise the elicitation is theatre. A project that outgrows a profile authors a new one against the profile contract and files it under the custom slot, then changes the profile name in configuration.",
+  "tags": [
+    "blueprint:observability-probe-endpoints",
+    "category:08-profile-swap"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/tacs/tac-1501-observability-probe-endpoints-profile-resolver.json

@@ -0,0 +1,39 @@
+{
+  "tacId": "TAC-1501-observability-probe-endpoints-profile-resolver",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Probe profile resolver",
+  "purpose": "Reads the operator-declared `probeInterface.profile` name and its per-profile options at process boot, loads the matching profile module (shipped or project-authored `custom:<name>`), validates the resolved profile against the profile contract, and hands the frozen profile object to the handler-set binder and the listener-topology binder. Nothing in the process reaches for a probe transport, path, or response contract except through the resolved profile object this component returns.",
+  "responsibilities": [
+    "Read `probeInterface.profile` from process configuration and refuse a missing or unrecognised value with a stable-coded error (AC-14101-2, AC-14101-3).",
+    "Load the matching profile module from the shipped set (`kubernetes`, `loadBalancer`, `uptimeMonitor`, `systemd`, `dockerHealthcheck`, `reverseProxy`) or from the project's `profiles/custom/<name>` slot when the name is `custom:<name>` (AC-14108-2).",
+    "Apply operator overrides from `probeInterface.options.<profile>` on top of the profile's declared defaults, then validate the merged object against the profile contract (transport, paths or transport-appropriate surface, responseContract, semanticModel, listener defaults) and refuse a partial profile with `PROBE_PROFILE_INCOMPLETE` (AC-14103-1, AC-14103-2).",
+    "Refuse a response-contract override that adds a field beyond the profile's enumerated response surface with `PROBE_RESPONSE_FIELD_REFUSED` (AC-14106-2).",
+    "Emit the exact-match auth-exempt path set for the resolved profile so the project's auth middleware installer can consume it and refuse a wildcard or prefix entry with a stable-coded error (AC-14107-3).",
+    "Return one frozen profile object per boot; expose no mutation surface after boot resolution."
+  ],
+  "internalStructure": "One module: a `resolveProbeProfile({ config, profileLoader, contractValidator })` function returning a frozen profile object plus a `getExemptPathSet()` accessor. The `profileLoader` is a small dispatcher that resolves the profile name to the shipped module or the `custom:<name>` project slot. The `contractValidator` is a schema-check function against the profile contract (transport enum, paths shape per transport, responseContract enum per transport, semanticModel enum). No I/O beyond the initial configuration read and the profile-module import; no cache invalidation because the resolved profile is treated as a boot-time constant.",
+  "interfaces": [
+    {
+      "name": "resolveProbeProfile",
+      "kind": "factory",
+      "description": "resolveProbeProfile({ config, profileLoader, contractValidator }) -> { profile, getExemptPathSet }. Called once at boot; the returned profile drives the handler-set binder (TAC-1502), the listener-topology binder (TAC-1503), and the non-HTTP adapter selector (TAC-1504)."
+    },
+    {
+      "name": "profileLoader",
+      "kind": "read-api",
+      "description": "Function that resolves a profile name to the profile module. Shipped profiles resolve to the blueprint's own modules; a `custom:<name>` value resolves to the project's `profiles/custom/<name>` slot. Injected so the project supplies its module discovery."
+    },
+    {
+      "name": "contractValidator",
+      "kind": "read-api",
+      "description": "Schema-check function against the profile contract. Returns a validated frozen profile object on success and a typed error naming the missing or extraneous field on refusal."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "The resolver is boot-time-only; a profile change requires a process restart, matching AC-14108-1's expectation. That trade removes a class of live-swap bugs (mid-request rebinding of listeners, half-installed auth-exempt lists) and makes the profile object trivially safe to pass around by reference. A project that wants hot-reload wires a supervisor that restarts the process gracefully; the resolver stays boot-time.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/tacs/tac-1502-observability-probe-endpoints-handler-set.json

@@ -0,0 +1,40 @@
+{
+  "tacId": "TAC-1502-observability-probe-endpoints-handler-set",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Probe handler set",
+  "purpose": "Owns the HTTP handlers each shipped profile binds. Each handler is a pure function of the resolved profile's response contract and the readiness predicate the profile installed. The handler set contains no per-profile branching outside this module; the resolver's profile object selects which handlers get built. The response body is generated strictly from the profile's enumerated response contract, so a field never appears on the wire that the contract did not declare.",
+  "responsibilities": [
+    "Build a liveness HTTP handler that returns the profile's pass response when the event loop is responsive and the profile's fail response otherwise (AC-14101-1, AC-14102-1, AC-14102-2).",
+    "Build a readiness HTTP handler that reads the operator-declared readiness predicate on invocation, returns the profile's pass response when the predicate is pass, and returns the profile's fail response when it is fail (AC-14102-3).",
+    "Build a single-signal health HTTP handler for profiles whose `semanticModel` equals `singleHealthSignal` (loadBalancer, uptimeMonitor, reverseProxy): the same predicate drives one handler whose pass and fail responses respect the profile's response contract, with content-length zero for body-less profiles (AC-14103-3, AC-14105-1, AC-14106-3).",
+    "Build a Kubernetes JSON handler whose parsed body is exactly `{\"status\":\"pass\"}` or `{\"status\":\"fail\"}` and no other keys, refusing at build time a contract that includes a field beyond `status` (AC-14105-2, AC-14106-2).",
+    "Refuse to emit any string on any handler response that matches an operator-declared dependency name, environment name, hostname, replica id, build hash, or commit sha; the response-writer is generated per profile response contract and cannot include a field the contract did not enumerate (AC-14106-1)."
+  ],
+  "internalStructure": "One module exporting a `buildHandlerSet({ profile, readinessPredicate, now })` function. The function returns a `{ handlers }` object whose keys match the profile's resolved probe path set (`/live`, `/ready` for kubernetes; `/health` for loadBalancer; the resolved path for others). Each handler is an async function `(req, res)` that reads the current pass or fail answer, chooses the pass or fail branch of the profile's response contract, and writes the response. The response-writer is a per-profile pure function generated from the contract; there is no shared writer that could accidentally include a field the contract omitted.",
+  "interfaces": [
+    {
+      "name": "buildHandlerSet",
+      "kind": "factory",
+      "description": "buildHandlerSet({ profile, readinessPredicate, now }) -> { handlers }. `profile` is the frozen object from TAC-1501. `readinessPredicate` is a project-supplied `() -> 'pass' | 'fail'` function (default: strict-any-fail over declared dependency cached state). `now` is a `() -> Date` for test isolation. Returns a map of resolved path to stateless async handler. Called once at boot."
+    },
+    {
+      "name": "readinessPredicate",
+      "kind": "read-api",
+      "description": "Project-supplied synchronous function returning the current readiness state as `'pass'` or `'fail'`. The handler set never reads dependency state directly; the predicate boundary is where per-project logic lives."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "profile resolver",
+      "kind": "tac",
+      "tacId": "TAC-1501-observability-probe-endpoints-profile-resolver",
+      "description": "Reads the frozen profile object this component builds handlers against."
+    }
+  ],
+  "tradeoffs": "The handler-set builder generates one response-writer per profile response contract; there is no polymorphic writer shared across profiles. This costs a small amount of duplication (the pass and fail branches for each profile shape are separate) and buys the invariant that a handler cannot emit a field the profile contract did not enumerate. The alternative (one generic writer that reads a field list at runtime) leaks the field-list surface into every handler and re-opens the class REQ-006 exists to close.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}