rcf-lite 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -6,6 +6,66 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-09-04
+
+Core companions train. Two new general-enterprise-practice blueprints land on the shipped core shelf, an additive companion-suggestion mechanism baked into the manifest, and the standards-derived-blueprint discipline written into the authoring standard as section 8a.
+
+### Added
+
+- **`observability-logging` v1.0.0 on the shelf.** New core blueprint (`blueprints/observability-logging/`), category `observability`, US band `15101-15899`, ADR/TAC suffix block `16xx`. Contributes five REQs, eight USs, two TACs (`TAC-1601-observability-logging-logger-factory`, `TAC-1602-observability-logging-redaction-boundary`), four ADRs. Declares `providesRoles: ["logging"]`. `ADR-1601-observability-logging-line-shape` is the shelf-canonical `scope: global` claimant on the `logging` global topic (transferred from `application-api-rest-ADR-304`, which is retained on api-rest as historical context without `scope: global` from api-rest v2.1.0). Ships the ECS-neutral single-line JSON emission contract, correlation identifier acceptance / propagation / reflection, PII redaction at the emission boundary by named category, operator-elicited minimum level per environment, and a hermetic in-memory capture mode for tests.
+
+- **`application-error-handling` v1.0.0 on the shelf.** New core blueprint (`blueprints/application-error-handling/`), category `application`, US band `16101-16899`, ADR/TAC suffix block `17xx`. Contributes four REQs, seven USs, two TACs (`TAC-1701-application-error-handling-boundary`, `TAC-1702-application-error-handling-record-factory`), three ADRs. Declares `providesRoles: ["errorHandling"]` and `suggestedCompanions: [{role: "logging", ...}]`. `ADR-1701-application-error-handling-record-shape` mints the `errorHandling` global topic (distinct from `errorEnvelope`, which stays with `application-api-rest` as the REST wire shape). Ships process-level and framework-level boundaries, the shared internal error record shape (code, category, message, correlationId, cause chain, redacted context), the transient / permanent / unknown classification vocabulary, and delegation of the wire mapping through a substitutable `transportWriter` interface.
+
+- **Companion-suggestion mechanism (spec section 2).** Two additive optional top-level fields on `blueprint.json`: `providesRoles: string[]` (lower camelCase; paired scope:global ADR on the topic string is required) and `suggestedCompanions: [{role, reason}]` (reason has em-dash and emoji refusals to keep operator-facing prose plain). A blueprint declaring neither still loads clean (every shelf blueprint outside this train). Deterministic tier ladder resolver (applied provider > registered library provider > core-shelf provider) with a project-level pin file `rcf/companions.json` (schemaVersion 1, current pin per role, `pinnedAt` ISO-8601, rides git) overriding the library + shelf tiers. Two library candidates for one role with no pin refuse exit 3 with a three-path resolution message (adopt at apply via `--companion`, pin project-wide via `rcf define blueprint companions set`, or `rcf define blueprint library remove` one of the libraries). Backward-compatible: a service blueprint that does not declare `suggestedCompanions[]` produces an empty resolution and prints no block.
+
+- **New CLI verbs and flags on `rcf define blueprint`.** `--companion <role>=<slug>` on `add` (repeatable) accepts `<libraryPrefix>:<slug>` for a library provider or a bare kebab slug for a shelf provider, preflight-refuses exit 2 when the named provider does not declare `providesRoles` containing the role (`--companion <role>=<slug>: blueprint '<slug>' does not declare providesRoles containing '<role>'.`), and writes the accepted pins to `rcf/companions.json`. `--no-companion-suggestions` on `add` suppresses both the preflight pin phase and the post-apply resolved suggestion block. `rcf define blueprint companions <slug>` prints the resolved companion set for an applied service blueprint with origin annotations (`already applied` / `pinned via rcf/companions.json` / `registered library '<prefix>' (overrides shelf provider <slug>)` / `shelf fallback (no registered library provides this role)`); refuses exit 3 on ambiguous libraries. `rcf define blueprint companions set <role> <slug>` writes a project-level pin; `unset <role>` removes it. `--json` on all three sub-verbs emits a machine-readable envelope preserving `suggestedCompanions[]` order.
+
+- **Apply-time suggestion block.** After a successful `rcf define blueprint add` on a service blueprint that declares `suggestedCompanions[]`, stdout carries a `Suggested companions this blueprint recommends alongside it:` header followed by one line per role in the shape `  <role>          -> <resolved-provider> (<origin>)`, then a `Apply either with: rcf define blueprint add <slug>` footer. The apply itself never adopts a companion (that is the operator's decision). Suppressed by `--no-companion-suggestions`.
+
+- **`rcf define validate` refuses exit 3 on an unresolvable pin (spec section 5).** When `rcf/companions.json` pins a role to a slug that no applied blueprint, no registered library and no shelf blueprint provides, validate exits 3 with the ratified message shape `rcf/companions.json pins role '<role>' to '<slug>' but no such provider is applied, registered or on the shelf.`. An absent companions.json is not itself an error.
+
+- **Standards-derived-blueprint discipline as authoring standard section 8a.** The rule is documented in `packages/rcf-lite/docs/blueprint-authoring.md` section 8a: MUST clauses become ACs where the clause binds a testable runtime or artefact behaviour; a MUST that binds an operator choice (choice-shaped) may land as a `recommendedDefault: true` ADR carrying the clause id on `standardsTraceClause`; SHOULD clauses become recommended ADR defaults; MAY clauses become elicited ADR choices; not-carried clauses stay allowed with a named reason. Three additive optional per-ADR-contribution fields on `blueprint.json`: `recommendedDefault: boolean`, `elicited: boolean`, `standardsTraceClause: string` (the standard clause identifier verbatim, or the sentinel `"generic enterprise practice"`). One additive optional blueprint-level field: `standardsTrace: [{id, version}]`. When `standardsTrace[]` is declared, every ADR contribution MUST carry a non-null `standardsTraceClause` (loader refusal shape: `blueprint '<slug>' declares standardsTrace but ADR contribution '<id>' has no standardsTraceClause; every ADR must reference a standard clause or the sentinel 'generic enterprise practice'.`, exit 2 at the CLI edge). No cross-check on clause severity to kind mapping (amendment A2 Baz 2026-09-04T12:20:31Z): the discipline is prose in section 8a, not code.
+
+- **Roles registry (section 6a).** `logging` (shelf provider `observability-logging`), `errorHandling` (shelf provider `application-error-handling`). New roles land in the registry with a chunk-zero-style edit at ratification time, no loader change.
+
+- **Companion-suggestion paragraph on the managed agent-instructions block.** `guidance/managed/agent-instructions-block.md` gains one paragraph under `How to talk to your operator` telling the agent to surface resolved companions verbally, prefer the library provider over the shelf when a library is registered, and never apply a companion without the operator's explicit go. `packages/rcf-lite/guidance/managed/agent-instructions-block.hash` regenerated to `129f4018f526ececaef7ae5bea19ecd72be03a957e2cf2ee3323e85f117f6cba`.
+
+### Changed
+
+- **`application-api-rest`: 2.0.0 -> 2.1.0** (minor bump: additive `suggestedCompanions[{role: "logging", ...}, {role: "errorHandling", ...}]`; `ADR-304-application-api-rest-logging` retained on the blueprint without `scope: global` and re-titled `Historical: ... (superseded by observability-logging-ADR-1601 as the shelf-canonical logging global-topic owner from api-rest v2.1.0)`; `docs/topics.md` records the transfer and adds the two new blueprints to the shelf-wide band registry).
+- **`application-spa`: 1.4.0 -> 1.5.0** (minor bump: additive `suggestedCompanions[{role: "logging", ...}, {role: "errorHandling", ...}]`; `docs/topics.md` shelf-wide band registry adds the two new blueprints).
+
+### Migration notes
+
+- A project on `application-api-rest` v2.0.0 re-applies at v2.1.0 with `rcf define blueprint add <path-to>/blueprints/application-api-rest`; the apply is a minor bump (new suggestedCompanions field, ADR-304 retained without scope:global). Existing chains that referenced `ADR-304-application-api-rest-logging` in their own docs keep the reference intact (the contribution is retained, only its global-topic claim was dropped).
+- A project that had superseded the `logging` topic at project level under v1.x keeps the supersede as historical context; `observability-logging` is the shelf-canonical claimant from this train onward, and a project that wants to align on the shelf provider re-applies both blueprints and drops any redundant historical resolution with `rcf define blueprint remove-resolution <adr-id>`.
+- A project on `application-spa` v1.4.0 re-applies at v1.5.0 for the additive `suggestedCompanions` field.
+- A project that wants the shelf `logging` role: `rcf define blueprint add <path-to>/blueprints/observability-logging`.
+- A project that wants the shelf `errorHandling` role: `rcf define blueprint add <path-to>/blueprints/application-error-handling`.
+- Dex's WSD library adopts the mechanism as a minor bump (0.4.0 -> 0.5.0 named as the adoption target in spec section 7): `wsd-logging` adds `providesRoles: ["logging"]`; `wsd-error-handling` adds `providesRoles: ["errorHandling"]`; `wsd-api-rest` adds `suggestedCompanions: [{role: "logging", ...}, {role: "errorHandling", ...}]`. Optional `standardsTrace[]` adoption formalises the prose standards-trace tables the library already ships.
+
+## [0.18.0] - 2026-09-04
+
+Core shelf probe-path alignment. One shelf blueprint owns the probe-path binding across the whole shelf: `observability-probe-endpoints` v1.1.0 is the sole `scope: global` claimant on `healthProbes` and `readinessSemantics` and gains an optional Kubernetes-profile `/startup` path (off by default, enabled per project by `probeInterface.options.kubernetes.startup.enabled: true`). `observability-essentials` v2.0.0 drops its two `scope: global` topic claims, drops the shipped `/healthz` and `/readyz` defaults from TAC-801/802 (`path` becomes required config with no default), and adds the stable-coded `PROBE_INTERFACE_PATHS_MISSING` boot refusal for essentials-alone projects that forget the config. `application-api-rest` v2.0.0 drops the literal `/healthz/live`, `/healthz/ready`, and `/healthz/startup` bindings from REQ-006, US-2108, TAC-306, and the US-2103 versioning exemption, deferring to the resolved probe path set the probe-endpoints blueprint emits via TAC-1501 `getExemptPathSet` (or to the project-supplied `probeInterface.paths` in the essentials-alone case). `rcf doctor` grows a `probe-path-owner` check that fires when more than one applied blueprint teaches probe paths, and `rcf define blueprint remove-resolution <adr-id>` is the paired remedy verb that drops a single `manifest.resolutions[]` entry by its `resolvedByAdrId`. Spec: `projects/rcf-lite-wsd/specs/rcf-lite-probe-path-alignment-spec-2026-09-04.md` (amendments A1 to A3). Chain: REQ-012 with US-1201/1202/1203/1204 and TS-034/035/036/037 on the rcf-lite own tree.
+
+### Added
+
+- **`rcf define blueprint remove-resolution <adr-id>`.** Drops a single `manifest.resolutions[]` entry by its `resolvedByAdrId`; writes nothing else and leaves the project-level ADR file at `rcf/adrs/<adr-id>.json` in place as historical context. Refuses exit 2 when `<adr-id>` is malformed or names no ADR on the project tree. Idempotent on re-run: when `<adr-id>` is a well-formed ADR id that still names an ADR on the tree but is no longer on any resolutions[] entry, prints `nothing to remove` and exits 0. This is the verb the `probe-path-owner` doctor check and spec section 9 name as the redundant-resolution remedy; before this change the message named a verb that did not exist. Chain: US-1204 with TS-037 on REQ-012 for the rcf-lite own tree; spec amendment A2 (2026-09-04, under the envelope after gate d-2026-09-04-016 finding 1); work item `w-2026-09-03-dave-021`.
+
+- **Core shelf probe-path alignment (spec 2026-09-04).** One owner on the shelf for the probe-path binding. `observability-probe-endpoints` v1.1.0 is the sole shelf-wide `scope: global` claimant on `healthProbes` and `readinessSemantics` and adds an optional third Kubernetes-profile path `startup` (default `/startup`, off by default, enabled per project by `probeInterface.options.kubernetes.startup.enabled: true`) with paired ACs on US-14102 (AC-14102-4: three-path resolution) and US-14107 (AC-14107-4: three-entry auth-exempt list). `observability-essentials` v2.0.0 drops its `scope: global` claims on `healthProbes` and `readinessSemantics` (ADR-801 and ADR-802 become scope-local historical ADRs with a title change; content body stays for reader context per spec section 4), restates REQ-001/002 path-neutral, drops the `/healthz` and `/readyz` defaults from TAC-801/802 (`path` becomes required config with no shipped default), and gains AC-7101-4 and AC-7102-4 covering the stable-coded `PROBE_INTERFACE_PATHS_MISSING` boot refusal for essentials-alone projects. `application-api-rest` v2.0.0 drops the literal `/healthz/live`, `/healthz/ready`, and `/healthz/startup` bindings from REQ-006, US-2108 (all eight ACs), TAC-306, and US-2103 (versioning-exemption AC), deferring to the resolved probe path set that `observability-probe-endpoints` emits via TAC-1501 `getExemptPathSet` (or the project-supplied `probeInterface.paths` in the essentials-alone case). The three-way alignment is verified by `packages/rcf-lite/test/blueprint/probe-path-alignment.test.js`: 15 tests covering the nine assertions of spec section 7 across the six permutations of applying the three amended blueprints. `rcf doctor` gains a `probe-path-owner` check that fires when more than one applied blueprint teaches probe paths (spec section 9). Chain: REQ-012 with US-1201/1202/1203 and TS-034/035/036 on the rcf-lite own chain records the WHAT of the alignment for the dogfood tree. Trace: `projects/rcf-lite-wsd/specs/rcf-lite-probe-path-alignment-spec-2026-09-04.md` (sections 1 through 11); origin: Dex WSD escalation 2026-09-03; work item `w-2026-09-03-dave-021`.
+
+### Changed
+
+- **`observability-probe-endpoints`: 1.0.0 -> 1.1.0** (minor bump per blueprint-authoring section 8: additive, no scope:global topic change).
+- **`observability-essentials`: 1.0.0 -> 2.0.0** (major bump: drops two `scope: global` topic claims and reshapes REQ/TAC bodies).
+- **`application-api-rest`: 1.0.0 -> 2.0.0** (major bump: shape change to REQ-006 and US-2108 AC set removes literal probe paths).
+
+### Migration notes
+
+- A project that applied only `observability-essentials` v1.x: re-applying to v2.0.0 requires one line of configuration per environment (`probeInterface.paths.liveness` and `probeInterface.paths.readiness`) to satisfy the essentials boot wiring, unless the project also composes `observability-probe-endpoints` v1.1.0 or later (which supplies the paths automatically).
+- A project that applied both `observability-essentials` v1.x and `observability-probe-endpoints` v1.0.0 with a project-level ADR superseding both on `healthProbes` and `readinessSemantics`: after re-apply, the resolutions are redundant historical context; `rcf doctor`'s `probe-path-owner` check flags them with the `rcf define blueprint remove-resolution` hint.
+- A project that applied `application-api-rest` v1.x: FBSes and TCs that bind literal `/healthz/live`, `/healthz/ready`, or `/healthz/startup` strings need one edit each to bind the resolved path set; `rcf audit coverage --strict` catches project-side TCs that still hold the literal strings after re-apply.
+
 ## [0.17.0] - 2026-09-04
 
 The e2e verification contract for browser-facing projects. Verify pins `@playwright/mcp@0.0.80` with a preflight print and a `--playwright-mcp-version` override for emergency use; the effective pin lands on the report's runStats. Doctor gains four browser-facing checks (`playwright-present`, `browser-present`, `playwright-mcp-reachable`, `playwright-mcp-redundant`) routed by an applied blueprint's `browserSurface`, with a one-line skip on API-only projects. Init writes a Playwright MCP entry only when no scope-visible signature exists, falling back to a distinctly named `playwright-rcf` project-scope entry when it cannot prove absence, and opt-out via `--no-playwright-mcp`. `application-spa` v1.4.0 and `delivery-ci-workflows` v2.2.0 ship the paired `browserSurface` stories and the illustrative e2e job as a documentation contract per spec 2026-09-03 amendment A2; the runtime materialiser lands in a follow-up train.

package/blueprints/application-api-rest/README.md

@@ -1,4 +1,4 @@
-# REST API blueprint (v1.0.0)
+# application-api-rest blueprint (v2.0.0)
 
 The second content blueprint on the rcf-build-lite blueprint mechanism (design brief v2, ratified; Phase 3 of the blueprint programme). Scope: a REST service, single deployable, versioned wire contract, no UI in scope. Composes with the application-spa blueprint by design, including two deliberate scope:global conflicts.
 
@@ -38,3 +38,7 @@ ADR-301 errorEnvelope, ADR-302 authModel, ADR-303 apiVersioning, ADR-304 logging
 ## Quality bar
 
 OpenAPI 3.1 generated from source with three-axis drift validation in the build; three k8s probes with specified schemas, security-auth-magic-link and log-noise exclusions, and documented failure modes; four auth classes enforced in middleware with x-auth-class contract validation; RFC 7807 on every failure path including pre-routing ones; cursor pagination with write-stability; strict unknown-parameter rejection; idempotency-key replay semantics with declared TTL; per-class rate limits with honest Retry-After; structured JSON logs, RED metrics, and OpenTelemetry spans off one shared request context; forward-only migrations with named reverts and a live /v1/_meta report; secrets never logged, PII redacted by stated policy, TLS outside development, CORS deny-by-default. Every bar is carried by ACs in the doc set, not by this README.
+
+## Breaking change in v2.0.0 (2026-09-04)
+
+This blueprint no longer binds literal probe path strings. The three probe surfaces (liveness, readiness, startup) are served at the RESOLVED paths supplied by either the composed observability-probe-endpoints blueprint (Kubernetes profile default `/live`, `/ready`, and, when enabled, `/startup`; loadBalancer profile default `/health`) or by project configuration under `probeInterface.paths` in the essentials-alone case. REQ-006, US-2108 (all eight ACs), TAC-306, and US-2103 (versioning-exemption AC) were reshaped. Spec: `projects/rcf-lite-wsd/specs/rcf-lite-probe-path-alignment-spec-2026-09-04.md` section 5. Migration: project FBSes and TCs that bind literal `/healthz/live`, `/healthz/ready`, or `/healthz/startup` strings become one edit each to bind the resolved path set; `rcf audit coverage --strict` catches project-side TCs that still hold the literal strings after re-apply. See CHANGELOG.md.

package/blueprints/application-api-rest/blueprint.json

@@ -1,6 +1,6 @@
 {
   "slug": "application-api-rest",
-  "version": "1.0.0",
+  "version": "2.1.0",
   "category": "application",
   "contributions": [
     {
@@ -237,9 +237,7 @@
     {
       "id": "ADR-304-application-api-rest-logging",
       "kind": "adr",
-      "path": "adrs/adr-304-application-api-rest-logging.json",
-      "scope": "global",
-      "topic": "logging"
+      "path": "adrs/adr-304-application-api-rest-logging.json"
     },
     {
       "id": "ADR-305-application-api-rest-pagination",
@@ -261,5 +259,15 @@
       "kind": "adr",
       "path": "adrs/adr-308-application-api-rest-rate-limiting.json"
     }
+  ],
+  "suggestedCompanions": [
+    {
+      "role": "logging",
+      "reason": "Every request pipeline pass writes a request-scoped log line; a logging companion supplies the factory the pipeline calls, and the shelf logging blueprint (observability-logging) is the fallback when no library provider is registered."
+    },
+    {
+      "role": "errorHandling",
+      "reason": "The error translator writes the wire envelope from the internal record; an error-handling companion supplies the record factory and the boundary that constructs it, and the shelf application-error-handling blueprint is the fallback when no library provider is registered."
+    }
   ]
 }

package/blueprints/application-api-rest/contributions/adrs/adr-304-application-api-rest-logging.json

@@ -2,12 +2,12 @@
   "adrId": "ADR-304-application-api-rest-logging",
   "prdId": "PRD-001",
   "tadId": "TAD-001",
-  "version": "1.0.0",
+  "version": "2.1.0",
   "status": "accepted",
-  "title": "Structured JSON lines with request-scoped correlation as the project's primary logging shape",
+  "title": "Historical: structured JSON lines with request-scoped correlation as the project's primary logging shape (superseded by observability-logging-ADR-1601 as the shelf-canonical logging global-topic owner from api-rest v2.1.0)",
   "context": "A project has one primary logging shape; aggregation, alerting, retention, and redaction tooling are all built against it, and mixed shapes halve the value of every query. The decision covers the line format, the mandatory fields, and where correlation ids live.",
   "decision": "Logs are single-line JSON objects. Mandatory base fields: timestamp, level, message, service name. Every request-scoped line additionally carries the request id, and the trace id when a trace context exists. Request completion lines carry method, path template, status, duration, and auth class at the class's declared level. Redaction (application-api-rest-REQ-016) applies before emission. Prose, multi-line, and printf-style lines are not emitted by application code (application-api-rest-REQ-012, application-api-rest-US-2114).",
-  "consequences": "Every operational question that logs can answer becomes a structured query keyed on the same ids the metrics and traces carry. The cost is log discipline in code review (no stray console prose) and marginally larger lines; both are prices the observability requirements already commit to. Any blueprint contributing log-emitting components to the same project joins this shape or the operator supersedes it project-wide.",
+  "consequences": "Every operational question that logs can answer becomes a structured query keyed on the same ids the metrics and traces carry. The cost is log discipline in code review (no stray console prose) and marginally larger lines; both are prices the observability requirements already commit to. Any blueprint contributing log-emitting components to the same project joins this shape or the operator supersedes it project-wide. From api-rest v2.1.0 the shelf-wide `logging` global topic is claimed only by `observability-logging` (ADR-1601-observability-logging-line-shape). The structured-JSON-with-correlation intent recorded here remains the intent for api-rest's server-side emission; the shelf-canonical topic owner is elsewhere. Projects that had superseded `logging` at project level in v1.x retain their supersede as historical context (see rcf define blueprint remove-resolution for the drop path when the resolution is genuinely redundant).",
   "alternativesConsidered": [
     {
       "name": "Human-readable prose lines",

package/blueprints/application-api-rest/contributions/requirements/application-api-rest-req-006.json

@@ -1,8 +1,8 @@
 {
   "reqId": "application-api-rest-REQ-006",
   "prdId": "PRD-001",
-  "title": "Kubernetes probe endpoints: liveness, readiness, and startup with specified schemas and exclusions",
-  "description": "The service exposes three probe endpoints. GET /healthz/live returns 200 whenever the process can serve any request and performs no dependency checks. GET /healthz/ready returns 200 only when declared downstream dependencies (database, cache, queues) are reachable, and 503 with a body listing the failed checks otherwise. GET /healthz/startup returns 200 once initialisation (migrations, cache warm, config load) is complete. Each probe has a specified response schema, sits outside the auth middleware, is excluded from info-level metrics and log noise, and has a documented failure mode.",
+  "title": "Probe endpoints: liveness, readiness, and startup with specified schemas and exclusions (paths resolved by the composed observability-probe-endpoints blueprint or by project configuration)",
+  "description": "The service exposes three probe endpoints: liveness, readiness, and startup, with specified response schemas and exclusions. The liveness probe returns 200 whenever the process can serve any request and performs no dependency checks. The readiness probe returns 200 only when declared downstream dependencies (database, cache, queues) are reachable, and 503 with a body listing the failed checks otherwise. The startup probe returns 200 once initialisation (migrations, cache warm, config load) is complete and a non-200 with the pending steps before that. Each probe has a specified response schema, sits outside the auth middleware and rate limiter, is excluded from info-level metrics and log noise, and has a documented failure mode. The probe PATHS are supplied by the composed `observability-probe-endpoints` blueprint (Kubernetes profile default: `/live`, `/ready`, and, when enabled, `/startup`), or by project-level configuration under `probeInterface.paths` in the essentials-alone case; this blueprint does not bind literal paths. When probe-endpoints is composed the auth-middleware installer consumes the exempt path set that probe-endpoints emits and no other, so the auth-exempt entries exactly match the resolved probe path set.",
   "category": "functional",
   "domain": "operability",
   "priority": "must",
@@ -11,8 +11,8 @@
     "blueprint:application-api-rest",
     "category:06-probe-endpoints"
   ],
-  "version": "1.0.0",
+  "version": "2.0.0",
   "status": "approved",
   "createdAt": "2026-08-19T10:00:00Z",
-  "updatedAt": "2026-08-19T10:00:00Z"
+  "updatedAt": "2026-09-04T00:00:00Z"
 }

package/blueprints/application-api-rest/contributions/tacs/tac-306-application-api-rest-operability.json

@@ -2,16 +2,17 @@
   "tacId": "TAC-306-application-api-rest-operability",
   "prdId": "PRD-001",
   "tadId": "TAD-001",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "status": "approved",
-  "name": "Operability: probes, lifecycle, migrations, and the meta endpoint",
+  "name": "Operability: probes (at resolved paths), lifecycle, migrations, and the meta endpoint",
   "purpose": "Owns what an orchestrator and an operator need from the outside: the three probe endpoints, the initialisation lifecycle they report on, the forward-only migration machinery, and the /v1/_meta version report.",
   "responsibilities": [
-    "Serve /healthz/live, /healthz/ready, and /healthz/startup with their specified schemas, exclusions, and documented failure modes (application-api-rest-REQ-006).",
-    "Run the initialisation sequence (config load, migrations, cache warm) and expose its progress to the startup probe (AC-2108-4).",
+    "Serve the three probe surfaces (liveness, readiness, startup) at their resolved paths, with the specified schemas, exclusions, and documented failure modes; the path resolution is delegated to observability-probe-endpoints when composed (Kubernetes profile default /live, /ready, and, when enabled, /startup) or to project-level probeInterface.paths configuration when composed with observability-essentials alone (application-api-rest-REQ-006).",
+    "Run the initialisation sequence (config load, migrations, cache warm) and expose its progress to the resolved startup probe when the startup path is bound (AC-2108-4).",
     "Register and execute declared readiness checks against downstream dependencies, reporting per-check results in the ready body (AC-2108-2, AC-2108-3).",
     "Apply migrations strictly forward with named reverts and deterministic ordering (application-api-rest-REQ-014).",
-    "Serve /v1/_meta reporting the live schema version and application version, sourced from the migration record, under a declared auth class (application-api-rest-US-2118)."
+    "Serve /v1/_meta reporting the live schema version and application version, sourced from the migration record, under a declared auth class (application-api-rest-US-2118).",
+    "Consume the resolved probe path set (produced by observability-probe-endpoints via TAC-1501 getExemptPathSet or derived from project probeInterface.paths configuration) as the exact auth-exempt list for the probe surfaces; refuse any hand-authored auth-exempt entry that duplicates or diverges from the resolved set (AC-2108-5)."
   ],
   "internalStructure": "A lifecycle coordinator owning initialisation state, a check registry the readiness probe iterates, and the migration runner; probe handlers are thin reads over this state, never performing work themselves.",
   "interfaces": [
@@ -23,7 +24,7 @@
     {
       "name": "probe endpoints",
       "kind": "http",
-      "description": "The three /healthz/* endpoints and /v1/_meta, with their specced response schemas."
+      "description": "The three probe surfaces (liveness, readiness, startup) at their resolved paths, and /v1/_meta, with their specified response schemas. The path resolution is delegated to observability-probe-endpoints or to project-level probeInterface.paths configuration; this TAC binds NO literal path strings for the probe surfaces from v2.0.0."
     }
   ],
   "dependencies": [
@@ -40,7 +41,7 @@
       "description": "Probe outcomes land in the dedicated probe metric."
     }
   ],
-  "tradeoffs": "Probe handlers reading pre-computed state (rather than checking dependencies inline) keeps probes cheap and non-amplifying under orchestrator polling, at the cost of a bounded staleness window in readiness reporting; the check interval is the tuning knob and is declared configuration.",
+  "tradeoffs": "Probe handlers reading pre-computed state (rather than checking dependencies inline) keeps probes cheap and non-amplifying under orchestrator polling, at the cost of a bounded staleness window in readiness reporting; the check interval is the tuning knob and is declared configuration. Path resolution is delegated so a project can compose the api-rest blueprint with either observability-probe-endpoints (elicit-and-adapt path set) or observability-essentials alone (project-supplied path set) without editing this TAC; the v2.0.0 breaking change is exactly this delegation.",
   "createdAt": "2026-08-19T10:00:00Z",
-  "updatedAt": "2026-08-19T10:00:00Z"
+  "updatedAt": "2026-09-04T00:00:00Z"
 }

package/blueprints/application-api-rest/contributions/user-stories/application-api-rest-us-2103.json

@@ -2,7 +2,7 @@
   "usId": "application-api-rest-US-2103",
   "prdId": "PRD-001",
   "reqId": "application-api-rest-REQ-003",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "status": "approved",
   "title": "Path-versioned contract with announced deprecation and a stated drop policy",
   "asA": "API consumer maintaining a long-lived integration",
@@ -14,7 +14,7 @@
       "description": "Every business endpoint lives under a major-version path prefix (/v1/...); only the probe endpoints and the documentation endpoints sit outside it.",
       "given": "the generated OpenAPI path inventory",
       "when": "paths are checked for the version prefix",
-      "then": "every path is version-prefixed except /healthz/*, /openapi.*, and /docs",
+      "then": "every path is version-prefixed except the resolved probe paths, /openapi.*, and /docs",
       "testable": true,
       "scope": "runtime"
     },
@@ -59,5 +59,5 @@
     "TAC-304-application-api-rest-resource-layer"
   ],
   "createdAt": "2026-08-19T10:00:00Z",
-  "updatedAt": "2026-08-19T10:00:00Z"
+  "updatedAt": "2026-09-04T00:00:00Z"
 }

package/blueprints/application-api-rest/contributions/user-stories/application-api-rest-us-2108.json

@@ -2,62 +2,62 @@
   "usId": "application-api-rest-US-2108",
   "prdId": "PRD-001",
   "reqId": "application-api-rest-REQ-006",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "status": "approved",
-  "title": "Liveness, readiness, and startup probes that tell the orchestrator the truth",
+  "title": "Liveness, readiness, and startup probes that tell the orchestrator the truth, at the resolved paths",
   "asA": "platform operator running the service under Kubernetes",
-  "iWant": "three probe endpoints that each answer their one question honestly and cheaply",
+  "iWant": "three probe endpoints (at their resolved paths) that each answer their one question honestly and cheaply",
   "soThat": "the orchestrator restarts, routes, and rolls out instances on real signals",
   "acceptanceCriteria": [
     {
       "id": "AC-2108-1",
-      "description": "GET /healthz/live returns 200 with the specified response schema whenever the process can serve any request, and performs no dependency checks whatsoever.",
-      "given": "a running instance with a deliberately unreachable database",
-      "when": "/healthz/live is called",
+      "description": "GET on the resolved liveness path returns 200 with the specified response schema whenever the process can serve any request, and performs no dependency checks whatsoever.",
+      "given": "a running instance with a deliberately unreachable database and the liveness path resolved either by observability-probe-endpoints (Kubernetes profile default /live) or by project configuration",
+      "when": "the resolved liveness path is called",
       "then": "it returns 200 against the specified schema, unaffected by the dependency outage",
       "testable": true,
       "scope": "runtime"
     },
     {
       "id": "AC-2108-2",
-      "description": "GET /healthz/ready returns 200 only when every declared downstream dependency check (database, cache, queues) passes.",
-      "given": "an instance with all declared dependencies reachable",
-      "when": "/healthz/ready is called",
+      "description": "GET on the resolved readiness path returns 200 only when every declared downstream dependency check (database, cache, queues) passes.",
+      "given": "an instance with all declared dependencies reachable and the readiness path resolved (Kubernetes profile default /ready) or supplied by project configuration",
+      "when": "the resolved readiness path is called",
       "then": "it returns 200 with the specified schema listing each check as passing",
       "testable": true,
       "scope": "runtime"
     },
     {
       "id": "AC-2108-3",
-      "description": "GET /healthz/ready returns 503 with a body enumerating the failed checks by name when any declared dependency is unreachable.",
-      "given": "an instance with one declared dependency down",
-      "when": "/healthz/ready is called",
+      "description": "GET on the resolved readiness path returns 503 with a body enumerating the failed checks by name when any declared dependency is unreachable.",
+      "given": "an instance with one declared dependency down and the readiness path resolved as above",
+      "when": "the resolved readiness path is called",
       "then": "it returns 503 and the body names the failing check while still listing the passing ones",
       "testable": true,
       "scope": "runtime"
     },
     {
       "id": "AC-2108-4",
-      "description": "GET /healthz/startup returns 200 only after initialisation (migrations applied, cache warmed, config loaded) completes, and a non-200 with the pending steps before that.",
-      "given": "an instance mid-initialisation and the same instance after initialisation",
-      "when": "/healthz/startup is called in each state",
+      "description": "GET on the resolved startup path returns 200 only after initialisation (migrations applied, cache warmed, config loaded) completes, and a non-200 with the pending steps before that. The startup path is available when the composed observability-probe-endpoints blueprint enables it via `probeInterface.options.kubernetes.startup.enabled: true` or the project supplies `probeInterface.paths.startup` in configuration.",
+      "given": "an instance mid-initialisation and the same instance after initialisation, with the startup path resolved (Kubernetes profile default /startup when enabled) or supplied by project configuration",
+      "when": "the resolved startup path is called in each state",
       "then": "the mid-initialisation call is non-200 naming pending steps; the post-initialisation call is 200",
       "testable": true,
       "scope": "runtime"
     },
     {
       "id": "AC-2108-5",
-      "description": "All three probes sit outside the auth middleware and outside rate limiting: they succeed with no credentials and are never 401, 403, or 429.",
-      "given": "a running instance",
-      "when": "each probe is called with no credentials at sustained frequency",
-      "then": "every call is answered on probe semantics alone, never with an auth or rate-limit status",
+      "description": "All three probes sit outside the auth middleware and outside rate limiting: the auth-middleware installer consumes exactly the resolved probe path set (the same list observability-probe-endpoints emits via TAC-1501 getExemptPathSet, or the exact set derived from `probeInterface.paths` in the essentials-alone case), so each probe succeeds with no credentials and is never 401, 403, or 429; adjacent routes never fall under the same exemption.",
+      "given": "a running instance with the resolved probe path set exposed to the auth-middleware installer",
+      "when": "each probe is called with no credentials at sustained frequency AND an adjacent user-traffic route is also called unauthenticated",
+      "then": "every probe call is answered on probe semantics alone, never with an auth or rate-limit status; the adjacent route returns the auth middleware unauthenticated response",
       "testable": true,
       "scope": "runtime"
     },
     {
       "id": "AC-2108-6",
-      "description": "Probe requests do not appear in info-level request logs and are excluded from RED endpoint metrics; probe outcomes are recorded under their own dedicated metric.",
-      "given": "a period of steady probe traffic",
+      "description": "Probe requests (at their resolved paths) do not appear in info-level request logs and are excluded from RED endpoint metrics; probe outcomes are recorded under their own dedicated metric.",
+      "given": "a period of steady probe traffic on the resolved probe paths",
       "when": "info-level logs and endpoint metrics are inspected",
       "then": "probe requests appear in neither, and the dedicated probe-outcome metric carries their results",
       "testable": true,
@@ -65,18 +65,18 @@
     },
     {
       "id": "AC-2108-7",
-      "description": "Each probe's response schema and failure mode are documented in the generated spec: what a failure body contains and what an operator should conclude from it.",
-      "given": "the generated OpenAPI document",
+      "description": "The generated OpenAPI document names the three probe surfaces (liveness, readiness, startup) and their resolved paths, plus each probes success and failure schemas and its documented failure mode; the resolved paths are computed at documentation-generation time from the composed observability-probe-endpoints blueprint or from project configuration.",
+      "given": "the generated OpenAPI document produced for a project that has resolved its probe paths",
       "when": "the three probe entries are read",
-      "then": "each declares its success and failure schemas and its documented failure mode",
+      "then": "each declares its success and failure schemas and its documented failure mode; every entry path is the resolved path (no legacy literal probe-path prefix appears in the generated document)",
       "testable": true,
       "scope": "runtime"
     },
     {
       "id": "AC-2108-8",
-      "description": "Readiness reflects recovery: when a failed dependency becomes reachable again, /healthz/ready returns to 200 without a process restart.",
+      "description": "Readiness reflects recovery: when a failed dependency becomes reachable again, GET on the resolved readiness path returns to 200 without a process restart.",
       "given": "an instance whose dependency outage has been restored",
-      "when": "/healthz/ready is called after restoration",
+      "when": "the resolved readiness path is called after restoration",
       "then": "it returns 200 without the process having restarted",
       "testable": true,
       "scope": "runtime"
@@ -86,5 +86,5 @@
     "TAC-306-application-api-rest-operability"
   ],
   "createdAt": "2026-08-19T10:00:00Z",
-  "updatedAt": "2026-08-19T10:00:00Z"
+  "updatedAt": "2026-09-04T00:00:00Z"
 }

package/blueprints/application-api-rest/docs/topics.md

@@ -9,7 +9,7 @@ This file is the application-api-rest half of the cross-blueprint contract; the
 | `errorEnvelope` | ADR-301-application-api-rest-error-envelope | Reused verbatim from the application-spa vocabulary | DELIBERATE pairing: application-spa contributes ADR-204-application-spa-error-envelope on this topic. Applying both blueprints to one project surfaces the conflict for operator resolution. Expected resolution: one project-level ADR adopting RFC 7807 end to end, superseding both halves |
 | `authModel` | ADR-302-application-api-rest-auth-model | Reused verbatim from the application-spa vocabulary | DELIBERATE pairing with SPA's ADR-205-application-spa-auth-model (cookie-based sessions, client half). Expected resolution: one project-level ADR fixing the credential transport and mapping the client session model onto the four server classes |
 | `apiVersioning` | ADR-303-application-api-rest-api-versioning | Minted here; pre-cleared as unclaimed in the application-spa vocabulary | The one versioning strategy for the project's wire contract. Any blueprint contributing a versioned API surface must join or supersede this decision |
-| `logging` | ADR-304-application-api-rest-logging | Minted here; pre-cleared as unclaimed in the application-spa vocabulary | The project's primary logging shape. Any blueprint contributing log-emitting server components conflicts here by design |
+| `logging` (retained historical) | ADR-304-application-api-rest-logging (no scope:global from v2.1.0) | Transferred to observability-logging-ADR-1601 as the shelf-canonical owner from v2.1.0 | The project's primary logging shape now sits on the shelf logging blueprint; the api-rest ADR-304 is retained as historical context and the api-rest blueprint no longer claims the global topic. Apply observability-logging 1.0.0 or later (or a registered library-side provider) to satisfy the `logging` role api-rest suggests |
 
 Rules for new topics (inherited from the application-spa vocabulary, 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 (`errorShape`, `auth`, `apiVersion`, `logShape` are all wrong).
 
@@ -22,20 +22,22 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | 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` |
+| application-api-rest | 2101-2899 | 3xx | shipped v2.1.0 (suggestedCompanions added) | `errorEnvelope`, `authModel`, `apiVersioning` |
 | 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` |
+| observability-essentials | 7101-7899 | 8xx | shipped v2.0.0 | `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` |
+| observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
+| observability-logging | 15101-15899 | 16xx | shipped v1.0.0 | `logging` |
+| application-error-handling | 16101-16899 | 17xx | shipped v1.0.0 | `errorHandling` |
 
 Suffix-family ids (ADR, TAC): SPA numbers in the 2xx range, this package takes 3xx (ADR-301 to ADR-308, TAC-301 to TAC-306); the next blueprint should take 4xx.
 

package/blueprints/application-api-rest/guide/application-api-rest.md

@@ -26,7 +26,7 @@ Any project whose primary surface is an HTTP API meant to be consumed by clients
 
 ## What a good outcome looks like
 
-Attack the finished service from the outside and try to catch it lying: fetch /docs and call an endpoint straight from the spec, send garbage JSON, reuse an idempotency key with a different body, hammer a public endpoint past its limit, kill the database and watch /healthz/ready tell the truth while /healthz/live stays up, grep the logs for the bearer token you just used. A build that honours this doc set answers every one of those correctly. That is the measure: what an integrating client and an on-call engineer get out of the box.
+Attack the finished service from the outside and try to catch it lying: fetch /docs and call an endpoint straight from the spec, send garbage JSON, reuse an idempotency key with a different body, hammer a public endpoint past its limit, kill the database and watch the resolved readiness path tell the truth while the resolved liveness path stays up, grep the logs for the bearer token you just used. A build that honours this doc set answers every one of those correctly. That is the measure: what an integrating client and an on-call engineer get out of the box.
 
 ## Your decisions that remain open
 
@@ -39,3 +39,7 @@ Attack the finished service from the outside and try to catch it lying: fetch /d
 ## Cost honesty
 
 This doc set makes an API slower to declare done, on purpose: 117 criteria is the price of "no endpoint ships undocumented, unmeasured, or unguarded". If you are prototyping a throwaway integration, that price is wrong; skip the blueprint rather than opting out of half of it. If other people's code will call this service, the price is the product.
+
+## Composing with observability-probe-endpoints and observability-essentials (v2.0.0)
+
+From v2.0.0 this blueprint no longer binds literal probe path strings. The three probe surfaces (liveness, readiness, startup) are served at the RESOLVED paths supplied by either the composed observability-probe-endpoints blueprint (Kubernetes profile default `/live`, `/ready`, and, when enabled, `/startup`; `loadBalancer` profile default `/health`) or by project configuration under `probeInterface.paths` in the essentials-alone case. The auth-middleware installer consumes exactly the exempt path set that observability-probe-endpoints emits via TAC-1501 `getExemptPathSet` (or the exact set derived from `probeInterface.paths` in the essentials-alone case); adjacent routes never fall under the same exemption. The generated OpenAPI document names each probe surface and its resolved path at documentation-generation time. The three-way composition invariants live in `packages/rcf-lite/test/blueprint/probe-path-alignment.test.js`.

package/blueprints/application-error-handling/README.md

@@ -0,0 +1,42 @@
+# Error-handling blueprint (v1.0.0)
+
+Transport-agnostic error-handling contract for a rcf-lite application. General enterprise practice, no vendor lock-in. Mints the `errorHandling` global topic on `ADR-1701-application-error-handling-record-shape` (distinct from `errorEnvelope`, which stays with application-api-rest as the REST wire shape). Provides the `errorHandling` role for the companion-suggestion mechanism. Suggests the `logging` companion so emission threads through the applied logging factory.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/application-error-handling
+```
+
+Applies namespaced contributions into the project tree and records `manifest.blueprints[]`.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version 1.0.0, category `application`, `providesRoles: ["errorHandling"]`, `suggestedCompanions: [{role: "logging", ...}]`, and the 16 contributions with scope/topic on `ADR-1701` |
+| Doc set | `contributions/` | 4 REQs, 7 USs (9 ACs), 2 TACs, 3 ADRs, schema-valid and namespaced |
+| Record schema | `assets/schemas/error-record.schema.json` | JSON Schema for the internal record shape |
+| Guide | `guide/application-error-handling.md` | Operator-facing: when to reach, when not, mechanism-reach gaps |
+| Coordination vocabulary | `docs/topics.md` | The `errorHandling` global topic distinct from `errorEnvelope`, the shelf-wide id band registry update |
+
+## What it contributes, and what it deliberately does not
+
+Contributed: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files.
+
+Deliberately not contributed: a transport wire envelope (application-api-rest owns REST via `errorEnvelope`; a future gRPC or message-consumer blueprint claims its own); a retry policy implementation (the record carries category; the applying platform's retry surface reads it); a substitute for the logging companion's own field-level redaction (the record's context field is redacted through the applied logging companion's redaction boundary, per AC-16104-1).
+
+## The one global decision
+
+`ADR-1701-application-error-handling-record-shape` ships `scope: global` on topic `errorHandling`. This is the project's internal error record shape (six fields: code, category, message, correlationId, cause, context). A composing blueprint that wants a different internal record shape conflicts here by design. `errorHandling` is distinct from `errorEnvelope` (owned by application-api-rest for REST); the internal record is one project decision above every transport-specific wire envelope.
+
+See `docs/topics.md` for the exact strings, the distinction from `errorEnvelope`, and the AC id band allocation (16101-16899, ADR/TAC suffix block 17xx).
+
+## Quality bar
+
+Process-level uncaught-exception boundary and framework-level pipeline boundary both registered; every record constructed through TAC-1702's factory with code and category required; context redacted at construction time using the applied logging companion's redaction categories; cause chain preserved across nested wrappings; classification vocabulary transient / permanent / unknown (elicited additions per project); transport response mapping delegated through the substitutable transportWriter interface (ADR-1703); emission routed through the applied logging companion factory with a documented stderr fallback when no companion is applied. Every bar is carried by ACs in the doc set.
+
+## Known mechanism-reach gaps
+
+- **Boundary coverage.** The blueprint cannot prove every code path routes through the boundary; a bare `console.error` or a `process.exit` from any code path bypasses the boundary. Project-side workaround: a grep gate as a project-authored TC bound to `AC-16106-1`.
+- **Classification integrity.** The vocabulary is enforced at the factory (code + category required), but the correctness of the category the caller chose is not machine-checkable. A caller who classifies every failure as `unknown` still passes the shape gate; the blueprint's guide names the diagnostic pattern.

package/blueprints/application-error-handling/assets/schemas/error-record.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://rcf-lite/blueprints/application-error-handling/schemas/error-record.schema.json",
+  "title": "Internal error record",
+  "description": "The shape TAC-1702's factory returns and every downstream consumer reads. Frozen; see ADR-1701.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["code", "category", "message", "correlationId", "context"],
+  "properties": {
+    "code": { "type": "string", "minLength": 1, "description": "Project-elicited machine-readable identifier." },
+    "category": { "type": "string", "minLength": 1, "description": "One of the ADR-1702 classification vocabulary." },
+    "message": { "type": "string", "minLength": 1, "description": "Human-readable message; no PII." },
+    "correlationId": { "type": ["string", "null"], "description": "Stamped from the ambient logging context at construction." },
+    "cause": { "anyOf": [ { "type": "null" }, { "$ref": "#" } ], "description": "Nested record for the wrapped cause, or null." },
+    "context": { "type": "object", "description": "Redacted at construction using the applied logging companion's redaction categories." }
+  }
+}

package/blueprints/application-error-handling/blueprint.json

@@ -0,0 +1,27 @@
+{
+  "slug": "application-error-handling",
+  "version": "1.0.0",
+  "category": "application",
+  "providesRoles": ["errorHandling"],
+  "suggestedCompanions": [
+    { "role": "logging", "reason": "The internal error record emits through the logging companion, not direct stdout or stderr writes; a logging companion supplies the factory the boundary calls." }
+  ],
+  "contributions": [
+    { "id": "application-error-handling-REQ-001", "kind": "req", "path": "requirements/application-error-handling-req-001.json" },
+    { "id": "application-error-handling-REQ-002", "kind": "req", "path": "requirements/application-error-handling-req-002.json" },
+    { "id": "application-error-handling-REQ-003", "kind": "req", "path": "requirements/application-error-handling-req-003.json" },
+    { "id": "application-error-handling-REQ-004", "kind": "req", "path": "requirements/application-error-handling-req-004.json" },
+    { "id": "application-error-handling-US-16101", "kind": "us", "path": "user-stories/application-error-handling-us-16101.json" },
+    { "id": "application-error-handling-US-16102", "kind": "us", "path": "user-stories/application-error-handling-us-16102.json" },
+    { "id": "application-error-handling-US-16103", "kind": "us", "path": "user-stories/application-error-handling-us-16103.json" },
+    { "id": "application-error-handling-US-16104", "kind": "us", "path": "user-stories/application-error-handling-us-16104.json" },
+    { "id": "application-error-handling-US-16105", "kind": "us", "path": "user-stories/application-error-handling-us-16105.json" },
+    { "id": "application-error-handling-US-16106", "kind": "us", "path": "user-stories/application-error-handling-us-16106.json" },
+    { "id": "application-error-handling-US-16107", "kind": "us", "path": "user-stories/application-error-handling-us-16107.json" },
+    { "id": "TAC-1701-application-error-handling-boundary", "kind": "tac", "path": "tacs/tac-1701-application-error-handling-boundary.json" },
+    { "id": "TAC-1702-application-error-handling-record-factory", "kind": "tac", "path": "tacs/tac-1702-application-error-handling-record-factory.json" },
+    { "id": "ADR-1701-application-error-handling-record-shape", "kind": "adr", "path": "adrs/adr-1701-application-error-handling-record-shape.json", "scope": "global", "topic": "errorHandling" },
+    { "id": "ADR-1702-application-error-handling-classification-vocabulary", "kind": "adr", "path": "adrs/adr-1702-application-error-handling-classification-vocabulary.json", "recommendedDefault": true, "elicited": true, "standardsTraceClause": "generic enterprise practice" },
+    { "id": "ADR-1703-application-error-handling-transport-mapping", "kind": "adr", "path": "adrs/adr-1703-application-error-handling-transport-mapping.json", "recommendedDefault": true, "elicited": false, "standardsTraceClause": "generic enterprise practice" }
+  ]
+}

package/blueprints/application-error-handling/contributions/adrs/adr-1701-application-error-handling-record-shape.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1701-application-error-handling-record-shape",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Internal error record shape: code, category, message, correlationId, cause chain, redacted context",
+  "context": "Without a shared record shape, every consumer of error data (log ingestion pipelines, alerting rules, wire-response mappers, retry policies) invents its own view. The record loses information at each hop and downstream tools reconstruct it from string parsing. The 'errorHandling' global topic is minted here (distinct from 'errorEnvelope', which stays with application-api-rest as the REST wire shape): errorHandling is the internal record shape and the uncaught-exception boundary; errorEnvelope is the wire format one transport chooses to translate the record into.",
+  "decision": "The internal error record has exactly six fields: code (string, machine-readable identifier the project elicits at record creation; the vocabulary is project-side), category (one of the ADR-1702 classification vocabulary), message (human-readable string, no PII), correlationId (stamped from the ambient logging context at construction time; may be null), cause (nested record for the wrapped cause, or null), context (redacted object per the applied logging companion's redaction categories). Records are constructed only through TAC-1702's factory; the factory refuses code or category missing.",
+  "consequences": "Log-side queries by code, category or correlationId all work off the shared field names. The wire-response mapper (ADR-1703) writes one envelope from the record without a per-project mapping table. The retry policy reads category at one place. The cause chain is preserved across wrappings without any consumer's per-layer knowledge. A future transport blueprint (gRPC, message consumer) claims its OWN transport-specific errorEnvelope topic; the internal record shape stays one project decision above.",
+  "alternativesConsidered": [
+    {
+      "name": "Free-form record with a message-plus-metadata bag",
+      "summary": "The record has message and a metadata object; every consumer looks up its own fields.",
+      "reasonNotChosen": "Loses the shared vocabulary and forces every consumer to invent field names; the failure mode is a per-consumer view that drifts silently."
+    },
+    {
+      "name": "Merge errorHandling and errorEnvelope into one global topic",
+      "summary": "One topic governs both the internal record and the wire envelope.",
+      "reasonNotChosen": "Conflates two decisions the mechanism gets to make separately: the internal record shape is one decision (this blueprint owns it); the wire envelope is a transport-specific decision (application-api-rest owns errorEnvelope for REST). Merging them forces a project to change the wire when it changes the internal record and vice versa."
+    }
+  ],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/application-error-handling/contributions/adrs/adr-1702-application-error-handling-classification-vocabulary.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-1702-application-error-handling-classification-vocabulary",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Classification vocabulary: transient, permanent, unknown by recommended default; operator elicits additions",
+  "context": "Retry policies are the difference between a self-healing system and a burning one. Classification at the source (where the code knows whether the failure was a transient network blip or a permanent authorisation refusal) puts the decision where the information is; classifying downstream on the wire is the source of most retry-storm outages. The recommended default set is deliberately small; per-domain additions land through elicited additions.",
+  "decision": "The recommended default classification vocabulary is transient, permanent, unknown. Every constructed record carries one string from this set. The applying operator elicits additional categories at apply (kebab or dotted-namespace grammar; refused with a boot error otherwise); elicited additions apply alongside the defaults. The transport response mapper reads the category and applies the per-class contract.",
+  "consequences": "Retry policies wire once against the shared vocabulary; per-project additions (rate-limited, quota-exceeded, dependency-degraded) fit in the same mechanism. The three defaults cover the majority of real-world classification decisions; a project that finds itself using unknown for everything has a diagnostic gap the classification is meant to catch.",
+  "alternativesConsidered": [
+    {
+      "name": "Enumerate an exhaustive vocabulary",
+      "summary": "The blueprint ships every possible category (auth, timeout, dependency, quota, ...) as recommended defaults.",
+      "reasonNotChosen": "Reliably fights every project's domain vocabulary; the three defaults plus elicited additions gives a working floor and a project-side extension path in the same round."
+    }
+  ],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}