rcf-lite 0.12.0 → 0.14.0

package/blueprints/observability-probe-endpoints/contributions/tacs/tac-1503-observability-probe-endpoints-listener-topology.json

@@ -0,0 +1,51 @@
+{
+  "tacId": "TAC-1503-observability-probe-endpoints-listener-topology",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Probe listener topology",
+  "purpose": "Binds the profile's HTTP probe handlers to the correct listener. When `probeListener.separatePort` is unset, the handlers bind to the user-traffic listener alongside application routes (fused topology). When `probeListener.separatePort: <N>` is set, the handlers bind to a dedicated HTTP listener on port N that serves only the profile's probe path set (separate-port topology). The topology component also produces the exact-match auth-exempt list the project auth middleware installer consumes so the exemption stays scoped to the resolved probe path set on the listener the handlers actually bound to.",
+  "responsibilities": [
+    "Read the resolved profile's `probeListener.separatePort` value; when unset, register the handler-set handlers at their resolved paths on the user-traffic listener (AC-14104-3).",
+    "When `probeListener.separatePort: <N>` is set, open a dedicated HTTP listener on port N and register the handler-set handlers at their resolved paths on that listener; do not register the same handlers on the user-traffic listener (AC-14104-1).",
+    "On the separate-port listener, refuse any registration beyond the profile's resolved probe path set; every other request on that listener returns not-found (AC-14104-2).",
+    "Emit the auth-exempt list for the topology in effect: on fused topology, the resolved probe path set with exact-match rules on the user-traffic listener; on separate-port topology, the resolved probe path set with exact-match rules on the separate probe listener and the invariant that no auth middleware runs on the separate listener (AC-14107-1, AC-14107-2).",
+    "Refuse an exempt-list entry that contains a wildcard character or a trailing slash implying a prefix with `PROBE_EXEMPT_MATCHER_INVALID` (AC-14107-3)."
+  ],
+  "internalStructure": "One module exporting a `bindListenerTopology({ profile, handlerSet, userTrafficListener, listenerFactory, exemptListInstaller })` function. When `profile.probeListener.separatePort` is set, the function calls `listenerFactory(port)` to obtain a new listener and registers handler-set entries on it; otherwise the function registers on the injected `userTrafficListener`. The function then hands the resulting exempt-path set to `exemptListInstaller`, which the project auth middleware installer consumes. Returns a `{ bound: [{ listener, path, handler }], exemptSet }` record.",
+  "interfaces": [
+    {
+      "name": "bindListenerTopology",
+      "kind": "factory",
+      "description": "bindListenerTopology({ profile, handlerSet, userTrafficListener, listenerFactory, exemptListInstaller }) -> { bound, exemptSet }. Called once at boot after TAC-1502 has built the handler set. The `userTrafficListener` is the project's HTTP router or server object; `listenerFactory(port)` is a project-supplied constructor for a fresh listener on the given port; `exemptListInstaller` is the project's auth-middleware exempt-list installer."
+    },
+    {
+      "name": "listenerFactory",
+      "kind": "read-api",
+      "description": "Project-supplied `(port: number) -> Listener` factory. Called only when the separate-port topology is in effect. Returns a new HTTP listener bound to the given port with no middleware installed."
+    },
+    {
+      "name": "exemptListInstaller",
+      "kind": "write-api",
+      "description": "Project-supplied installer that receives a `{ listener, paths: string[], matcher: 'exact' }` record and registers the exempt set with the auth middleware on the named listener. Refuses on the topology component's side if the paths carry a wildcard or prefix marker."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "profile resolver",
+      "kind": "tac",
+      "tacId": "TAC-1501-observability-probe-endpoints-profile-resolver",
+      "description": "Reads the frozen profile object for its resolved probe path set and separate-port declaration."
+    },
+    {
+      "name": "handler set",
+      "kind": "tac",
+      "tacId": "TAC-1502-observability-probe-endpoints-handler-set",
+      "description": "Binds the handlers this component built to the resolved listener."
+    }
+  ],
+  "tradeoffs": "The topology component holds no opinion on which listener library the project uses; it delegates listener construction to a project-supplied factory and delegates auth-middleware wiring to a project-supplied installer. That keeps the blueprint portable across Node HTTP servers, framework routers (Express, Hono, Fastify), and Worker-style edge platforms; it costs the project two small wiring functions per apply. The alternative (a blueprint-owned listener implementation) would double as a framework choice and takes on the maintenance load without the portability payoff.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/tacs/tac-1504-observability-probe-endpoints-non-http-adapters.json

@@ -0,0 +1,39 @@
+{
+  "tacId": "TAC-1504-observability-probe-endpoints-non-http-adapters",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Non-HTTP probe adapters",
+  "purpose": "Owns the non-HTTP transports the shipped profile set names: `dockerHealthcheck` (exec-transport, an entry-point command whose exit code is the probe answer), `systemd` (supervisor-notify transport, an `sd_notify(READY=1)` at boot followed by periodic `WATCHDOG=1` calls at the operator-configured cadence), and TCP-socket transport (a listener that completes the TCP handshake on pass and refuses the connection on fail, used by the Kubernetes `TCPSocket` probe mode when the operator selects it). No HTTP listener is opened for a process running only a non-HTTP profile.",
+  "responsibilities": [
+    "For the `dockerHealthcheck` profile, expose an entry-point command whose invocation reads the readiness predicate and exits with code 0 on pass and a non-zero code on fail; the process itself opens no HTTP probe listener (AC-14105-3).",
+    "For the `systemd` profile with `Type=notify`, call `sd_notify(READY=1)` exactly once after the process reaches its ready state at boot; when a watchdog cadence is declared, call `sd_notify(WATCHDOG=1)` at that cadence for the process lifetime.",
+    "For a Kubernetes profile whose `transport` override is `tcpSocket`, open a TCP listener on the resolved probe port; on pass, accept the connection and close it cleanly; on fail, close the accept socket so the kubelet's connect attempt is refused.",
+    "Ensure a non-HTTP profile's adapter selection is exclusive: the process does not open a probe HTTP listener when the selected profile's transport is `exec`, `notify`, or `tcpSocket` (AC-14105-3)."
+  ],
+  "internalStructure": "Three sibling submodules gated by the profile's `transport` value: `execAdapter` exposes a `runHealthcheck({ readinessPredicate })` function suitable for a Dockerfile `HEALTHCHECK CMD`; `notifyAdapter` exposes `announceReady()` and `startWatchdog({ cadenceMs })` helpers wrapping the operator-supplied notify implementation; `tcpAdapter` exposes `openTcpProbeListener({ port, readinessPredicate })`. The profile resolver's `transport` value selects exactly one adapter per boot; the rest stay dormant.",
+  "interfaces": [
+    {
+      "name": "selectAdapter",
+      "kind": "factory",
+      "description": "selectAdapter({ profile, readinessPredicate, notifyImplementation, tcpFactory }) -> { adapter }. Returns the correct adapter object for the profile's transport. `notifyImplementation` is a project-supplied `(msg: string) -> void` wrapping the supervisor notify call for the runtime (systemd's `NOTIFY_SOCKET` on Linux, a stub in tests). `tcpFactory` is a project-supplied `(port) -> TcpListener`. Called once at boot when the profile transport is non-HTTP."
+    },
+    {
+      "name": "notifyImplementation",
+      "kind": "write-api",
+      "description": "Project-supplied notify writer accepting a supervisor-format message string. For systemd, this writes to the `NOTIFY_SOCKET` datagram address. For tests, a stub accumulator. Injected so the blueprint holds no operating-system-specific dependency."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "profile resolver",
+      "kind": "tac",
+      "tacId": "TAC-1501-observability-probe-endpoints-profile-resolver",
+      "description": "Selects which non-HTTP adapter to instantiate from the frozen profile's transport value."
+    }
+  ],
+  "tradeoffs": "The non-HTTP transports the blueprint supports out of the box are the three that appear most on the supervisor conventions the shipped profile set targets. Other supervisor transports (gRPC health, a custom binary protocol) belong to a project-authored `custom:<name>` profile that supplies its own adapter through the same selection surface; the blueprint declines to ship every possible non-HTTP transport because the maintenance cost outstrips the value at the rcf-lite tier this blueprint targets. The alternative (a universal transport-abstraction interface) leaks its shape into every profile and every consumer without a real payoff for the three transports actually shipped.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/user-stories/observability-probe-endpoints-us-14101.json

@@ -0,0 +1,46 @@
+{
+  "usId": "observability-probe-endpoints-US-14101",
+  "prdId": "PRD-001",
+  "reqId": "observability-probe-endpoints-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Operator declares the target integration and the process materialises the profile at boot",
+  "asA": "operator deploying the service under an external supervising system",
+  "iWant": "the process to shape its probe surface from one profile declaration and refuse to start if that declaration is missing or invalid",
+  "soThat": "the probe wiring reflects the supervisor conventions the service actually runs under, and a mis-declared profile is caught at boot rather than on a silent probe miss in production",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-14101-1",
+      "description": "A process configured with `probeInterface.profile: kubernetes` boots and binds probe handlers whose paths and port topology match the resolved Kubernetes profile.",
+      "given": "a process configuration whose profile declaration resolves to `kubernetes` with default paths and fused-listener topology",
+      "when": "the process boots and its probe-binding step completes",
+      "then": "the running listener answers GET on the profile-declared liveness path (default /live) with 200 and on the profile-declared readiness path (default /ready) with 200 or 503, and no probe handler is bound at any path outside the profile-declared set",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-14101-2",
+      "description": "A process configured without a `probeInterface.profile` declaration and no shipped default refuses to boot with a stable-coded error naming the missing declaration.",
+      "given": "a process configuration whose profile declaration is absent and whose environment has removed the shipped default",
+      "when": "the process boots and its profile-resolution step runs",
+      "then": "the process exits with a non-zero code and emits a `PROBE_PROFILE_MISSING` error naming the declaration field the operator must set",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-14101-3",
+      "description": "A process configured with an unknown profile name refuses to boot with a stable-coded error naming the unknown value and the valid profile set.",
+      "given": "a process configuration whose profile declaration is `some-unknown-profile`",
+      "when": "the process boots and its profile-resolution step runs",
+      "then": "the process exits with a non-zero code and emits a `PROBE_PROFILE_UNKNOWN` error whose message contains the offending value and the enumerated valid profile names",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1501-observability-probe-endpoints-profile-resolver",
+    "TAC-1502-observability-probe-endpoints-handler-set"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/user-stories/observability-probe-endpoints-us-14102.json

@@ -0,0 +1,46 @@
+{
+  "usId": "observability-probe-endpoints-US-14102",
+  "prdId": "PRD-001",
+  "reqId": "observability-probe-endpoints-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A Kubernetes-supervised replica is probed at /live and /ready on the request-traffic listener with no operator configuration",
+  "asA": "kubelet running a probing loop against a pod that applied the blueprint with no explicit configuration",
+  "iWant": "the pod to answer HTTP GET probes at /live and /ready on the container's request-traffic port immediately after boot",
+  "soThat": "the standard Kubernetes livenessProbe and readinessProbe of shape httpGet: { path: /live, port: <containerPort> } and httpGet: { path: /ready, port: <containerPort> } work without further wiring",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-14102-1",
+      "description": "A running process on the shipped Kubernetes default answers GET /live with status 200 whenever the event loop is responsive.",
+      "given": "a process booted on the shipped `kubernetes` profile default with no operator override, running normally with its event loop responsive",
+      "when": "an unauthenticated GET is issued against `/live` on the request-traffic listener port",
+      "then": "the response status code is 200 and the JSON body equals `{\"status\":\"pass\"}`",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-14102-2",
+      "description": "The liveness handler on the shipped Kubernetes default performs zero downstream network calls per probe hit.",
+      "given": "a network-egress observer attached to the liveness handler on a process running the shipped `kubernetes` default",
+      "when": "a GET is issued against `/live`",
+      "then": "the observer records zero egress connections attributable to the handler between request receipt and response send",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-14102-3",
+      "description": "A running process on the shipped Kubernetes default answers GET /ready with 200 when the operator-declared readiness predicate is pass and 503 when it is fail.",
+      "given": "a process booted on the shipped `kubernetes` profile default with a readiness predicate wired against a stubbed dependency state",
+      "when": "the stubbed state is set to pass and a GET is issued against `/ready`, then the stubbed state is set to fail and a GET is issued again",
+      "then": "the first response has status 200 and body `{\"status\":\"pass\"}`; the second response has status 503 and body `{\"status\":\"fail\"}`",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1502-observability-probe-endpoints-handler-set",
+    "TAC-1503-observability-probe-endpoints-listener-topology"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/user-stories/observability-probe-endpoints-us-14103.json

@@ -0,0 +1,46 @@
+{
+  "usId": "observability-probe-endpoints-US-14103",
+  "prdId": "PRD-001",
+  "reqId": "observability-probe-endpoints-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Every profile the blueprint ships names its transport, path, response contract, and semantic distinction; a partial profile is refused at boot",
+  "asA": "operator choosing between the shipped profiles for a deployment context",
+  "iWant": "each profile to declare its transport, path, response, and semantic model completely, and any partial profile to be refused before it wires anything",
+  "soThat": "a mis-authored profile does not silently bind an incomplete probe surface that answers wrongly for the supervisor at hand",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-14103-1",
+      "description": "Each of the shipped profiles (`kubernetes`, `loadBalancer`, `uptimeMonitor`, `systemd`, `dockerHealthcheck`, `reverseProxy`) resolves to a config object whose `transport`, `paths` (or command/notify equivalent), `responseContract`, and `semanticModel` fields are all present and each carries a value from its enumerated set.",
+      "given": "a process configured with any one of the shipped profile names and no overrides",
+      "when": "the profile resolver runs at boot",
+      "then": "the resolved profile object has non-null `transport`, non-empty `paths` or its transport-appropriate equivalent, non-null `responseContract`, and non-null `semanticModel`",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-14103-2",
+      "description": "A profile whose configuration is missing any one of transport, path/command/notify surface, response contract, or semantic model is refused at boot with a stable-coded error naming the missing field.",
+      "given": "a process configured with a profile whose override removes the transport declaration",
+      "when": "the profile resolver runs at boot",
+      "then": "the process exits with a non-zero code and emits a `PROBE_PROFILE_INCOMPLETE` error naming the missing field and the profile name",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-14103-3",
+      "description": "The `loadBalancer` profile resolves to a single-endpoint HTTP GET at `/health` (or the configured override) with a `semanticModel` value of `singleHealthSignal`; distinct liveness and readiness handlers are not bound.",
+      "given": "a process configured with `probeInterface.profile: loadBalancer`",
+      "when": "the profile resolver runs and the handler set binds",
+      "then": "exactly one HTTP GET handler is bound at the profile's resolved path (default `/health`), no handler is bound at `/live` or `/ready`, and the resolved profile's `semanticModel` equals `singleHealthSignal`",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1501-observability-probe-endpoints-profile-resolver",
+    "TAC-1502-observability-probe-endpoints-handler-set"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/user-stories/observability-probe-endpoints-us-14104.json

@@ -0,0 +1,45 @@
+{
+  "usId": "observability-probe-endpoints-US-14104",
+  "prdId": "PRD-001",
+  "reqId": "observability-probe-endpoints-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The separate-port option binds probe handlers to a dedicated listener and keeps user traffic clean of them",
+  "asA": "operator running a Kubernetes deployment that publishes only the traffic port on the Service",
+  "iWant": "probe handlers bound to a container port distinct from the traffic port when I set `probeListener.separatePort`",
+  "soThat": "probes reach the pod on the kubelet-only port while the public Service never sees a probe path",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-14104-1",
+      "description": "When `probeListener.separatePort: <N>` is set on the Kubernetes profile, probe handlers bind to port N and no probe handler is bound on the user-traffic listener.",
+      "given": "a process configured with `probeInterface.profile: kubernetes` and `probeListener.separatePort: 9091` with a distinct user-traffic port",
+      "when": "the process boots and the topology binds",
+      "then": "a GET against `/live` on port 9091 returns 200, a GET against `/live` on the user-traffic port returns 404 (or the project's default not-found response), and a GET against `/ready` on the user-traffic port returns 404",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-14104-2",
+      "description": "The separate probe listener binds only the profile's resolved probe path set; any other path returns not-found on the probe listener.",
+      "given": "a process on the Kubernetes profile with `probeListener.separatePort: 9091` and a user-authored `/api/orders` route on the traffic listener",
+      "when": "a GET against `/api/orders` is issued against port 9091",
+      "then": "the response status is 404 (or the profile's declared not-found), and the request is not routed to the `/api/orders` handler",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-14104-3",
+      "description": "The default topology remains fused (probes bind on the user-traffic listener) when `probeListener.separatePort` is unset.",
+      "given": "a process on the Kubernetes profile with no `probeListener.separatePort` override",
+      "when": "the process boots and the topology binds",
+      "then": "GET `/live` on the user-traffic listener returns 200 and no additional listener is opened",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1503-observability-probe-endpoints-listener-topology"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/user-stories/observability-probe-endpoints-us-14105.json

@@ -0,0 +1,46 @@
+{
+  "usId": "observability-probe-endpoints-US-14105",
+  "prdId": "PRD-001",
+  "reqId": "observability-probe-endpoints-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Each profile's response contract is exactly what its supervisor reads and nothing more",
+  "asA": "operator whose service is probed by a supervisor with a fixed idea of what a probe response looks like",
+  "iWant": "the response contract to match the supervisor's shape and stay minimal",
+  "soThat": "the supervisor's parsing never sees an unexpected field and the surface never carries operational detail the supervisor does not read",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-14105-1",
+      "description": "The `loadBalancer` profile answers with an empty response body and the resolved status code (200 pass, 503 fail).",
+      "given": "a process on the `loadBalancer` profile whose readiness predicate is pass, then fail",
+      "when": "an HTTP GET is issued against the resolved health path in each state",
+      "then": "the pass response has status 200 with content-length 0 and no body; the fail response has status 503 with content-length 0 and no body",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-14105-2",
+      "description": "The `kubernetes` profile answers with a JSON body of exactly `{\"status\":\"pass\"}` or `{\"status\":\"fail\"}` and no additional keys.",
+      "given": "a process on the `kubernetes` profile with liveness pass and readiness pass, then readiness fail",
+      "when": "an HTTP GET is issued against `/live` and `/ready` in each state and the parsed JSON body key set is inspected",
+      "then": "the parsed body is exactly a one-key object whose only key is `status` and whose value is `pass` or `fail` matching the resolved answer",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-14105-3",
+      "description": "The `dockerHealthcheck` profile exits with code 0 on pass and a non-zero code on fail; the profile emits no HTTP surface.",
+      "given": "a process configured with `probeInterface.profile: dockerHealthcheck` and the profile's readiness predicate pass, then fail",
+      "when": "the profile's healthcheck command entry point is invoked in each state",
+      "then": "the pass invocation exits with code 0; the fail invocation exits with a non-zero code; the process opens no HTTP probe listener when this profile is selected",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1502-observability-probe-endpoints-handler-set",
+    "TAC-1504-observability-probe-endpoints-non-http-adapters"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/user-stories/observability-probe-endpoints-us-14106.json

@@ -0,0 +1,45 @@
+{
+  "usId": "observability-probe-endpoints-US-14106",
+  "prdId": "PRD-001",
+  "reqId": "observability-probe-endpoints-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "External-visible probe responses expose no internal identifier or operational value",
+  "asA": "operator whose probe surface is reachable by anyone who resolves the traffic host",
+  "iWant": "the probe response to carry no dependency name, environment, hostname, replica id, build hash, or metric",
+  "soThat": "the surface never fingerprints the service to a reader who was not meant to inspect the internal shape",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-14106-1",
+      "description": "The Kubernetes profile's `/live` and `/ready` responses contain no substring matching a declared dependency name, environment name, hostname, replica identifier, build hash, or commit sha.",
+      "given": "a process on the Kubernetes profile with declared dependencies `paymentsProvider` and `primaryStore`, environment `live`, hostname `svc-abc-123`, build hash `deadbeef`, commit sha `abcd1234abcd1234abcd1234abcd12341234abcd`",
+      "when": "an HTTP GET is issued against `/live` and against `/ready` and each response body is scanned for the tokens above",
+      "then": "no scan finds any of the tokens on either response body",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-14106-2",
+      "description": "The profile validator refuses a profile override that adds a field beyond the enumerated response contract at boot.",
+      "given": "a profile configuration that adds a `dependencies` array to the Kubernetes profile's response body",
+      "when": "the profile validator runs at boot",
+      "then": "the process exits with a non-zero code and emits a `PROBE_RESPONSE_FIELD_REFUSED` error naming the offending field and the profile name",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-14106-3",
+      "description": "The load-balancer and reverse-proxy profile responses contain content-length zero on every request.",
+      "given": "a process on the `loadBalancer` profile and a second process on the `reverseProxy` profile, both booted normally",
+      "when": "HTTP GET requests are issued against the resolved health path on each process for both pass and fail states",
+      "then": "every response carries `Content-Length: 0` and the response body is empty",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1502-observability-probe-endpoints-handler-set"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/user-stories/observability-probe-endpoints-us-14107.json

@@ -0,0 +1,45 @@
+{
+  "usId": "observability-probe-endpoints-US-14107",
+  "prdId": "PRD-001",
+  "reqId": "observability-probe-endpoints-REQ-007",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The probe paths sit on the project's auth-exempt list scoped exactly to the resolved set on the resolved listener",
+  "asA": "operator running the service behind an auth middleware that rejects unauthenticated requests by default",
+  "iWant": "the supervisor's probe requests to bypass auth on exactly the profile-resolved probe paths and only on the listener the profile bound those handlers to",
+  "soThat": "the supervisor gets the answer without a credential it cannot present and no adjacent route falls under the same exemption",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-14107-1",
+      "description": "On the Kubernetes profile with fused topology and an auth middleware that rejects unauthenticated requests, GET on the resolved `/live` and `/ready` paths returns the probe status; GET on any other user-traffic route returns the middleware's unauthenticated response.",
+      "given": "a process on the Kubernetes profile with fused topology, a project auth middleware installed on the user-traffic listener that returns 401 on unauthenticated requests, and a user-authored `/api/orders` route on that listener",
+      "when": "unauthenticated GET requests are issued to `/live`, `/ready`, `/api/orders`, and `/ready/next`",
+      "then": "`/live` and `/ready` return 200 or 503 per the probe answer; `/api/orders` returns 401; `/ready/next` returns the route's normal handler-or-not-found response after the middleware runs (a match on `/ready/next` is not treated as an exempt path)",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-14107-2",
+      "description": "On the Kubernetes profile with separate-port topology, the separate probe listener does not install the project auth middleware and answers probes without an auth challenge; the user-traffic listener answers `/live` and `/ready` under normal auth rules.",
+      "given": "a process on the Kubernetes profile with `probeListener.separatePort: 9091` and a project auth middleware installed on the user-traffic listener",
+      "when": "unauthenticated GET requests are issued to `/live` and `/ready` on both port 9091 and on the user-traffic port",
+      "then": "the port-9091 requests return the probe status; the user-traffic-port requests return the auth middleware's unauthenticated response",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-14107-3",
+      "description": "The exemption list produced by the profile at boot enumerates exactly the resolved probe path set, scoped by exact-match rules, and is refused if any entry contains a wildcard or prefix syntax.",
+      "given": "the exemption list produced by the profile resolver on the Kubernetes profile default",
+      "when": "the exemption-list emitter runs and the produced entries are inspected",
+      "then": "the list contains exactly the strings `/live` and `/ready` and their exact-match matcher rule; any injected entry containing `*` or a trailing slash to imply a prefix causes the emitter to refuse with a stable-coded error",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1503-observability-probe-endpoints-listener-topology"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/contributions/user-stories/observability-probe-endpoints-us-14108.json

@@ -0,0 +1,46 @@
+{
+  "usId": "observability-probe-endpoints-US-14108",
+  "prdId": "PRD-001",
+  "reqId": "observability-probe-endpoints-REQ-008",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Switching the target integration is a configuration change that takes effect on next boot",
+  "asA": "operator moving a service from one supervising system to another",
+  "iWant": "the shift to be a change to the profile name and its options and nothing else",
+  "soThat": "the migration cost is bounded and the source tree stays free of per-supervisor conditionals",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-14108-1",
+      "description": "A running service on the `kubernetes` profile, reconfigured to `probeInterface.profile: loadBalancer` and restarted, binds a single `/health` handler with the `singleHealthSignal` semantic model without changes to the source tree.",
+      "given": "a process booted on `kubernetes` default, and the same source tree with only `probeInterface.profile` changed to `loadBalancer` in configuration",
+      "when": "the process restarts on the new configuration and the topology binds",
+      "then": "a GET against `/health` returns 200 or 503; no probe handler is bound at `/live` or `/ready`; a source-tree diff between the two boots contains no non-configuration changes",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-14108-2",
+      "description": "A profile switch that requires a new custom profile is authored against the profile contract and filed under `profiles/custom/<name>` in the project; the switch is then a configuration change to `probeInterface.profile: custom:<name>`.",
+      "given": "a project that authored a `custom:tcpOnly` profile against the profile contract at `profiles/custom/tcpOnly.js` (or equivalent)",
+      "when": "the operator sets `probeInterface.profile: custom:tcpOnly` in configuration and the process restarts",
+      "then": "the resolver loads the custom profile, the topology binds the profile's declared surface, and no additional source-tree change is required to move between the shipped set and the custom profile",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-14108-3",
+      "description": "The profile-resolver call site is a single import point in the process boot path; the source-tree scan finds no per-profile conditional outside the profile modules and the resolver itself.",
+      "given": "the project's boot-path source tree",
+      "when": "a scan searches for `probeInterface.profile` usage and per-profile branching (e.g., `if (profile === 'kubernetes')`) outside the `profiles/` directory and the profile-resolver module",
+      "then": "the scan finds exactly one usage of `probeInterface.profile` (the resolver invocation) and zero per-profile conditionals in the rest of the boot path",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1501-observability-probe-endpoints-profile-resolver",
+    "TAC-1502-observability-probe-endpoints-handler-set"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/observability-probe-endpoints/docs/topics.md

@@ -0,0 +1,51 @@
+# observability-probe-endpoints blueprint coordination vocabulary
+
+This file is the observability-probe-endpoints 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.5.0 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-probe-endpoints contribution | Origin | Composition note |
+|---|---|---|---|
+| `healthProbes` | ADR-1501-observability-probe-endpoints-health-probes | Reused from the observability-essentials vocabulary (observability-essentials contributes a self-supervised two-endpoint HTTP JSON contract on the request-traffic listener at the same topic string). This blueprint contributes an elicit-from-target-integration-profile model on the same topic string on purpose. | The one project-wide decision on the health probe interface. Composing this blueprint with observability-essentials fires a `globalAdrTopic` conflict by design because the two blueprints answer different questions: essentials commits to a self-supervised HTTP JSON floor; this blueprint commits to an elicit-and-adapt model whose shape follows the external supervisor. Expected resolution: one project-level ADR that either commits to the elicit-and-adapt model (external supervisor drives the shape) or the fused self-supervised model (project owns the shape) or an explicit hybrid with boundaries |
+| `readinessSemantics` | ADR-1502-observability-probe-endpoints-readiness-semantics | Reused from the observability-essentials vocabulary (observability-essentials contributes strict-any-fail-over-declared-deps as the project-wide readiness rule at the same topic string). This blueprint contributes per-profile readiness semantics on the same topic string on purpose. | The one project-wide readiness semantics decision. Composing with observability-essentials fires a `globalAdrTopic` conflict by design. Expected resolution: one project-level ADR that commits to one of the two rules or an explicit hybrid |
+
+The observability-probe-endpoints blueprint claims two global topics. Every other contribution is scope-local (ADR-1503 the Kubernetes default, ADR-1504 the separate-port option, and ADR-1505 the external-response secrecy rule do not contribute global topics; a composing blueprint that holds an opinion on the default profile, on probe-listener topology, or on response secrecy authors its own project-level ADR if it wants to override).
+
+Note on the deliberate conflict with observability-essentials: this blueprint is designed for the EXTERNAL-SYSTEM INTEGRATION case (orchestrators, load balancers, uptime monitors probing the service, with their conventions driving the wire shape). observability-essentials is designed for the SELF-SUPERVISED all-in-one case (probes plus public status page plus notification outcome sink for a project that designs its own observability floor). Both are legitimate; each is the right default for its case. The conflict is the mechanism telling the operator to pick one intentionally. Precedent for the vendor-sibling pattern: security-auth-clerk conflicts with security-auth-magic-link on `authModel` on purpose; persistence-data-d1 conflicts with persistence-data-sqlite on both `persistenceStore` and `migrationDiscipline` on purpose. This blueprint follows the same pattern on `healthProbes` and `readinessSemantics`.
+
+Note on the delineation from observability-essentials's `statusPageContract` topic: this blueprint does not contribute an opinion on the public status page. A project that wants the probe surface from this blueprint AND the public status page and notification outcome sink from observability-essentials resolves the two `healthProbes` and `readinessSemantics` conflicts with project-level ADRs and keeps `statusPageContract` on the essentials-supplied side; the blueprints then compose without further conflict.
+
+Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, delivery-ci-workflows, observability-essentials, security-secrets-management, security-auth-clerk, email-smtp-resend, and deploy-cloudflare-workers 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 (`probeInterface`, `probeSurface`, `probes`, `livenessReadiness`, `probeTransport` are all wrong when `healthProbes` already exists; `readinessAggregation`, `readyPolicy`, `readinessRule` are all wrong when `readinessSemantics` already exists).
+
+## Id number bands (registry bootstrap)
+
+AC ids (and therefore US numeric ids, which anchor them) are NOT namespaced by the 0.5.0 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` |
+| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
+| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
+| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
+| security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
+| security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
+| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
+| persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics` |
+
+US 14101-14108 sit at the LOW end of the 14101-14899 band on purpose. A project-side story that mechanically derives from an observability-probe-endpoints REQ id into the number `14108` would collide against observability-probe-endpoints-US-14108 in this package; the band leaves headroom at the HIGH end (US 14181-14899) so a project's own stories anchored to observability-probe-endpoints REQs can allocate without conflict. The watchpost run4 lesson applies here too. Band spacing between the previous HQ-lane row (persistence-data-d1, 13101-13899, 14xx) and this one (14101-14899, 15xx) reflects the four-digit widening pattern opened by security-auth-clerk at 10xx and continued through the round-2 HQ lane.
+
+## Shared expectations for future composing blueprints
+
+- Reuse `healthProbes` exactly as spelled here when your blueprint holds an opinion on the health probe interface; contribute your own scope:global ADR on that string and let composition surface the pairing. A future blueprint that ships a metrics-probe hybrid or a health-check protocol variant (an OpenTelemetry-agent-scrape probe, a JMX health surface) will conflict here by design and expect a project-level ADR resolution.
+- Reuse `readinessSemantics` exactly as spelled here when your blueprint holds an opinion on readiness aggregation or its evaluator cadence.
+- The Kubernetes default (ADR-1503), the separate-port option (ADR-1504), and the external-response secrecy rule (ADR-1505) are scope-local. A composing blueprint that holds a different opinion on the default profile, the listener topology, or the response surface authors its own project-level ADR; none of them are minted as globals because the space of legitimate variations is smaller than the space of legitimate `healthProbes` variations.
+- 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), `deploymentPackaging` (unclaimed; a natural global for a container-image or artefact-bundling blueprint that composes above the deploy target). 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.