rcf-lite 0.12.0 → 0.13.0

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

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