rcf-lite 0.12.0 → 0.13.0

package/blueprints/application-api-rest/contributions/adrs/adr-308-application-api-rest-rate-limiting.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-308-application-api-rest-rate-limiting",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Rate limits keyed to auth classes with per-endpoint overrides",
+  "context": "Rate limiting needs a policy anchor: something stable that limits attach to. Candidates are one global limit, per-endpoint hand-tuning, or the auth classes the surface already declares.",
+  "decision": "Limits attach to the four auth classes, keyed per caller within each class (identity for user and admin, service principal for service, client address for public). Endpoints may declare an override of their class default in the same metadata record that declares their class; the override is published in the generated spec. Rejections are 429 with an honest Retry-After and the problem-details envelope, counted in metrics without per-rejection error logs (application-api-rest-REQ-011, application-api-rest-US-2113).",
+  "consequences": "Every endpoint has a correct default limit the moment it declares its class, and the override path keeps expensive endpoints protectable without inventing policy per route. Per-caller keying means fairness inside a class. The cost is a shared counter store across instances and the operational duty to tune class defaults from observed traffic rather than leaving initial guesses forever.",
+  "alternativesConsidered": [
+    {
+      "name": "One global limit",
+      "summary": "A single requests-per-window ceiling for the whole service.",
+      "reasonNotChosen": "Always mis-sized in both directions: generous enough for service peers means meaningless against anonymous abuse; tight enough for abuse throttles legitimate integrations."
+    },
+    {
+      "name": "Per-endpoint hand-tuned limits",
+      "summary": "Every endpoint declares its own limit with no class defaults.",
+      "reasonNotChosen": "N endpoints times M caller populations of bespoke policy, most of it copy-pasted; the class layer captures the real structure and leaves overrides for the genuine exceptions."
+    }
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-api-rest-REQ-001",
+  "prdId": "PRD-001",
+  "title": "Resource modelling: noun-based plural collections with an explicit representation model",
+  "description": "The API models its surface as resources, not procedures: URLs name nouns in plural collection form, hierarchy appears only where a relationship is genuinely 1:N and always scoped by the parent, collection filters live on sub-resources or query parameters rather than verb-shaped paths, and every resource class has one explicit, documented representation model.",
+  "category": "functional",
+  "domain": "resources",
+  "priority": "must",
+  "rationale": "A verb-shaped or ad-hoc URL surface cannot be paginated, filtered, cached, or documented consistently. One declared resource model is the anchor every other requirement in this blueprint binds to: the OpenAPI contract enumerates it, pagination and filtering conventions apply per collection, and auth classes attach per endpoint.",
+  "tags": [
+    "blueprint:application-api-rest",
+    "category:01-resource-modelling"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-api-rest-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Wire contract: JSON only, consistent casing, RFC-3339 UTC timestamps, explicit content types",
+  "description": "Every request and response body is JSON. Property casing is consistent across the whole surface (camelCase by default; a project may configure another casing but must then apply it everywhere). Timestamps are ISO-8601 in RFC-3339 form, UTC, on every temporal field. Every response carries an explicit Content-Type header; no response relies on client-side sniffing.",
+  "category": "technical",
+  "domain": "wire-contract",
+  "priority": "must",
+  "rationale": "Mixed casing, local-time timestamps, and implicit content types are the classic silent-drift defects of hand-grown APIs: each one costs every client an adapter. Declaring the wire contract once, as requirements with acceptance criteria, makes deviation a test failure instead of a client workaround.",
+  "tags": [
+    "blueprint:application-api-rest",
+    "category:02-wire-contract"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-api-rest-REQ-003",
+  "prdId": "PRD-001",
+  "title": "API versioning: major version in the URL path with declared deprecation and sunset behaviour",
+  "description": "The wire contract is versioned by major version in the URL path (/v1/...). Breaking changes require a new major version. Deprecated versions announce their retirement with Deprecation and Sunset headers on every response, and the project states its version-drop policy (minimum notice period, what clients receive after drop) as part of the contract.",
+  "category": "technical",
+  "domain": "versioning",
+  "priority": "must",
+  "rationale": "Versioning is a whole-project decision with no room for two answers, which is why the strategy ships as a scope-global decision record (ADR-303-application-api-rest-api-versioning). Encoding the version in the path keeps it visible in logs, caches, and browser tooling, and the sunset headers turn version retirement from a surprise outage into a scheduled migration.",
+  "tags": [
+    "blueprint:application-api-rest",
+    "category:03-versioning"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-api-rest-REQ-004",
+  "prdId": "PRD-001",
+  "title": "OpenAPI auto-generation: spec generated from source at build time, served with interactive documentation",
+  "description": "An OpenAPI 3.1 specification is generated from the implementation source at build time, never hand-written and maintained in parallel. The generated spec is served at /openapi.json and /openapi.yaml, and interactive documentation (Swagger UI or an equivalent renderer over the same spec) is served at /docs. The generated spec and the implementation cannot drift: every declared endpoint has an OpenAPI entry, every OpenAPI entry has an implementation, and response schemas match at the type level.",
+  "category": "technical",
+  "domain": "api-documentation",
+  "priority": "must",
+  "rationale": "A hand-written spec is a second implementation of the API that decays the moment someone forgets to edit it. Generating from source makes the spec a build artefact with the same freshness guarantee as the binary, and the drift criteria turn contract accuracy into something the build verifies rather than something a reviewer hopes for.",
+  "tags": [
+    "blueprint:application-api-rest",
+    "category:04-openapi-generation"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-api-rest-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Auth classes: every endpoint routed into exactly one of four declared middleware classes",
+  "description": "The service defines four distinct auth middleware classes, and every endpoint declares membership of exactly one: public (no auth processed, rate-limited), authenticated user (session or bearer token, identity resolved, standard rate limit), admin (authenticated plus admin role, elevated rate limit, audit-logged), and service-to-service (mTLS or signed request, no user identity, separate rate limit, audit-logged). The declared class is published in the OpenAPI extension x-auth-class, middleware enforces it server-side, and an endpoint without a declared class fails contract validation.",
+  "category": "security",
+  "domain": "auth",
+  "priority": "must",
+  "rationale": "Auth applied per-endpoint by convention is auth that one forgotten decorator silently removes. Making the class a declared, contract-validated property means the auth posture of the whole surface is enumerable from the spec, enforced by middleware rather than by handler discipline, and testable class by class. This is one half of the project's authentication model; the decision ships scope-global (ADR-302-application-api-rest-auth-model) because a project can only have one answer.",
+  "tags": [
+    "blueprint:application-api-rest",
+    "category:05-auth-classes"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "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.",
+  "category": "functional",
+  "domain": "operability",
+  "priority": "must",
+  "rationale": "A service without honest probes either gets restarted when it is healthy or kept in rotation when it cannot serve. Separating liveness from readiness from startup is what lets an orchestrator make three different decisions correctly; specifying schemas and exclusions keeps the probes cheap, quiet, and impossible to break by tightening auth.",
+  "tags": [
+    "blueprint:application-api-rest",
+    "category:06-probe-endpoints"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-api-rest-REQ-007",
+  "prdId": "PRD-001",
+  "title": "Pagination: cursor-based by default with a bounded page size and a navigable envelope",
+  "description": "Collection endpoints paginate with cursors by default (?cursor=...&limit=...). The response envelope carries next and prev cursors, the service enforces an explicit maximum limit, and total counts are optional and off by default because computing them is expensive. Cursors are opaque to clients and remain stable across concurrent writes to the collection.",
+  "category": "functional",
+  "domain": "pagination",
+  "priority": "must",
+  "rationale": "Offset pagination degrades quadratically on deep pages and skips or duplicates rows under concurrent writes. Cursor pagination as the declared default, with the envelope and limits specified up front, prevents each collection growing its own incompatible dialect.",
+  "tags": [
+    "blueprint:application-api-rest",
+    "category:07-pagination"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-api-rest-REQ-008",
+  "prdId": "PRD-001",
+  "title": "Filtering and sorting: documented parameters per resource, strict rejection of unknown parameters",
+  "description": "Every collection endpoint documents its filter parameter names per resource, sorting follows the ?sort=field,-field2 convention (leading minus for descending, comma-separated multi-key), and a request carrying an unknown query parameter is rejected with 400 and a problem-details response naming the offending parameter, never silently ignored.",
+  "category": "functional",
+  "domain": "querying",
+  "priority": "must",
+  "rationale": "Silently ignored parameters are the cruellest API defect: the client believes it filtered and acts on the unfiltered result. Strict rejection converts typos and stale client code into immediate, diagnosable 400s, and the single sort convention keeps every collection queryable the same way.",
+  "tags": [
+    "blueprint:application-api-rest",
+    "category:08-filtering-sorting"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-api-rest-REQ-009",
+  "prdId": "PRD-001",
+  "title": "Error envelope: RFC 7807 problem details on every error response, no ad-hoc bodies",
+  "description": "Every error response carries an RFC 7807 problem-details body: type, title, status, detail, instance, plus declared service-specific extensions. Client errors (4xx) and server errors (5xx) have distinct, documented shapes within the envelope. No error path anywhere in the service returns an ad-hoc body, a bare string, or an empty body with only a status code.",
+  "category": "functional",
+  "domain": "errors",
+  "priority": "must",
+  "rationale": "Clients can only build reliable error handling against a shape that holds everywhere, including the paths nobody planned: auth failures, rate limits, malformed JSON, unhandled exceptions. The wire error shape is a whole-project decision shared with whatever consumes the API, so it ships as a scope-global decision record (ADR-301-application-api-rest-error-envelope) that composition deliberately surfaces against a client-tier blueprint's matching decision.",
+  "tags": [
+    "blueprint:application-api-rest",
+    "category:09-error-envelope"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-api-rest-REQ-010",
+  "prdId": "PRD-001",
+  "title": "Idempotency: declared Idempotency-Key handling on non-safe verbs with server-side de-duplication",
+  "description": "Non-safe verbs (POST, and any PATCH whose double application would harm) accept an Idempotency-Key header. The project declares which verbs and resource classes require the key; for those, the server de-duplicates by key in a cache with a declared TTL, replaying the original response on repeats within the TTL and rejecting key reuse with a different request body.",
+  "category": "functional",
+  "domain": "idempotency",
+  "priority": "must",
+  "rationale": "Every client on a real network retries. Without server-side idempotency a retried payment is a double charge and a retried creation is a duplicate row. Declaring the covered verbs and resource classes as requirements, and the TTL as a decision (ADR-306-application-api-rest-idempotency), makes safe-retry a verifiable property rather than a hope.",
+  "tags": [
+    "blueprint:application-api-rest",
+    "category:10-idempotency"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-api-rest-REQ-011",
+  "prdId": "PRD-001",
+  "title": "Rate limiting: per auth class, with compliant 429 responses and per-endpoint overrides",
+  "description": "Rate limits are defined per auth class (public, authenticated user, admin, service-to-service each carry their own limit), a limited request receives 429 with a Retry-After header and a problem-details body, and individual endpoints may declare an override of their class default where the resource cost justifies it.",
+  "category": "nonFunctional",
+  "domain": "rate-limiting",
+  "priority": "must",
+  "rationale": "One global limit is always wrong twice: too loose for anonymous traffic, too tight for trusted service callers. Binding limits to the auth classes the endpoints already declare gives every request a correct default, and the specified 429 shape means well-behaved clients can back off mechanically.",
+  "tags": [
+    "blueprint:application-api-rest",
+    "category:11-rate-limiting"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-api-rest-REQ-012",
+  "prdId": "PRD-001",
+  "title": "Observability baseline: structured logs, RED metrics per endpoint, OpenTelemetry-compatible traces",
+  "description": "The service emits structured JSON logs with a request id on every request-scoped line, trace-id propagation, and a declared log level per auth class. Metrics cover RED (request rate, error rate, duration) per endpoint, counters per auth class, and probe outcomes. Traces are OpenTelemetry-compatible spans per request, with span attributes for auth class, resource id, and response status.",
+  "category": "technical",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "An unobservable service converts every incident into archaeology. Specifying the three signals as requirements, with the logging shape as a scope-global decision (ADR-304-application-api-rest-logging) because a project gets exactly one primary logging shape, means the first production incident is answerable with the telemetry the build already shipped.",
+  "tags": [
+    "blueprint:application-api-rest",
+    "category:12-observability"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-api-rest-REQ-013",
+  "prdId": "PRD-001",
+  "title": "Request-id propagation: every request carries or is assigned an id that survives the whole call chain",
+  "description": "Every inbound request either carries an X-Request-Id header or is assigned one at the edge. The response echoes the id, every request-scoped log line includes it, and every downstream call the service makes on behalf of the request propagates it, so one id follows one user action across every hop.",
+  "category": "technical",
+  "domain": "correlation",
+  "priority": "must",
+  "rationale": "Correlation is the cheapest observability there is and the most painful to retrofit. One header, generated at the edge and threaded everywhere, is what turns a support ticket containing a single id into a complete cross-service timeline.",
+  "tags": [
+    "blueprint:application-api-rest",
+    "category:13-request-id"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-api-rest-REQ-014",
+  "prdId": "PRD-001",
+  "title": "Migrations and schema versioning: forward-only migrations with named reverts and a version endpoint",
+  "description": "Database migrations are forward-only, each with a named revert step; the deploy order relative to application rollout is stated; and GET /v1/_meta reports the current schema version and application version so operators and tooling can confirm what is actually running.",
+  "category": "technical",
+  "domain": "migrations",
+  "priority": "must",
+  "rationale": "Schema changes are the deploys that cannot be blindly rolled back. Forward-only with named reverts forces every migration author to answer the undo question at write time, and the _meta endpoint replaces guessing about a running instance's schema state with reading it.",
+  "tags": [
+    "blueprint:application-api-rest",
+    "category:14-migrations"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-api-rest-REQ-015",
+  "prdId": "PRD-001",
+  "title": "Contract conformance: every OpenAPI-declared endpoint verified for request, response, error, and auth behaviour",
+  "description": "Every endpoint declared in the generated OpenAPI spec is verified on three axes: a schema-conforming request returns a schema-conforming response, an invalid request returns the declared error envelope, and the endpoint's declared auth class is enforced. The verification is derived from the spec so new endpoints are covered by construction, not by remembering.",
+  "category": "technical",
+  "domain": "contract-verification",
+  "priority": "must",
+  "rationale": "A contract nobody verifies is documentation, not a contract. Expressing conformance as acceptance criteria lets the implementing agent build the contract tests through the project's normal build cycle, and deriving coverage from the spec closes the gap where the newest endpoint is always the least tested.",
+  "tags": [
+    "blueprint:application-api-rest",
+    "category:15-contract-tests"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-api-rest-REQ-016",
+  "prdId": "PRD-001",
+  "title": "REST security baselines: clean logs, stated PII policy, TLS everywhere real, explicit CORS",
+  "description": "No secrets (tokens, keys, passwords, session identifiers) appear in logs at any level. The service states its PII-redaction policy and applies it to logs and error details. TLS is required in every non-development environment. The CORS policy is explicit and deny-by-default, with per-endpoint overrides declared rather than a wildcard.",
+  "category": "security",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "These four are the security defects that pass every functional test: the token in the debug log, the email address in the stack trace, the plaintext internal hop, the * CORS header that shipped as a temporary fix. Naming them as requirements with acceptance criteria puts them inside the build cycle's verification rather than outside it.",
+  "tags": [
+    "blueprint:application-api-rest",
+    "category:16-security-baselines"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

package/blueprints/application-api-rest/contributions/tacs/tac-301-application-api-rest-request-pipeline.json

@@ -0,0 +1,48 @@
+{
+  "tacId": "TAC-301-application-api-rest-request-pipeline",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Request pipeline",
+  "purpose": "Owns the ordered middleware chain every request traverses: request-id assignment, auth-class enforcement, rate limiting, idempotency handling, body parsing with strict content-type and parameter validation, and the terminal error boundary that guarantees the problem-details envelope on every failure path.",
+  "responsibilities": [
+    "Assign or accept X-Request-Id at the very edge, before any other middleware, and expose it to everything downstream (application-api-rest-REQ-013).",
+    "Invoke the auth middleware slot matching the endpoint's declared class before any handler code runs (application-api-rest-REQ-005).",
+    "Apply per-class and per-endpoint rate limits after identity resolution so limits key on the right principal (application-api-rest-REQ-011).",
+    "Enforce the wire contract at the boundary: reject unsupported content types with 415, malformed JSON with 400, unknown query parameters with 400 (application-api-rest-REQ-002, application-api-rest-REQ-008).",
+    "Run idempotency-key de-duplication for operations declared key-required (application-api-rest-REQ-010).",
+    "Convert every error, thrown or returned, into the RFC 7807 envelope as the final middleware; no path escapes it (application-api-rest-REQ-009).",
+    "Exempt the probe endpoints from auth, rate limiting, and info-level logging while keeping them inside request-id handling (application-api-rest-REQ-006)."
+  ],
+  "internalStructure": "A declaratively ordered middleware stack applied to every route from one composition point; per-endpoint variation (auth class, rate override, idempotency requirement) comes from endpoint metadata, never from hand-wiring middleware per route.",
+  "interfaces": [
+    {
+      "name": "endpoint metadata",
+      "kind": "configuration",
+      "description": "Per-endpoint declarations (auth class, rate-limit override, idempotency requirement) consumed to parameterise the shared pipeline; the same declarations the contract surface publishes."
+    },
+    {
+      "name": "error boundary",
+      "kind": "middleware",
+      "description": "Terminal handler converting any failure into a problem-details response with the request id in the instance field."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Auth middleware",
+      "kind": "tac",
+      "tacId": "TAC-302-application-api-rest-auth-middleware",
+      "description": "The pipeline hosts the four class slots; the auth component implements them."
+    },
+    {
+      "name": "Observability",
+      "kind": "tac",
+      "tacId": "TAC-305-application-api-rest-observability",
+      "description": "The pipeline emits the request-scoped log, metric, and span signals the observability component defines."
+    }
+  ],
+  "tradeoffs": "A single shared pipeline trades per-route micro-optimisation for one verifiable ordering: auth before rate limiting before handlers, and one error boundary. The ordering is load-bearing for the security ACs; bypassing the pipeline for a special route is the defect class this component exists to prevent.",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

package/blueprints/application-api-rest/contributions/tacs/tac-302-application-api-rest-auth-middleware.json

@@ -0,0 +1,41 @@
+{
+  "tacId": "TAC-302-application-api-rest-auth-middleware",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Auth middleware: the four class slots",
+  "purpose": "Implements the four auth classes as distinct middleware slots (public, user, admin, service) so every endpoint's auth posture is a declared class membership enforced in one place, not handler-by-handler discipline.",
+  "responsibilities": [
+    "Public slot: process no auth headers, resolve no identity, apply the public rate key (client address).",
+    "User slot: resolve identity from a session or bearer token, expose it to the handler, reject unresolvable identity with 401.",
+    "Admin slot: require resolved identity plus the admin role, reject non-admins with 403, audit-log every request with identity, endpoint, outcome, and request id.",
+    "Service slot: authenticate the calling service via mTLS or request signature, resolve a service principal and no user identity, audit-log every request, reject user or admin tokens outright.",
+    "Emit the auth-class attribute for logs, metrics, and spans so every signal is class-attributable (application-api-rest-REQ-012).",
+    "Guarantee the four slots are the only auth code paths in the service (AC-2106-6)."
+  ],
+  "internalStructure": "One slot implementation per class behind a common contract, selected by the endpoint's declared x-auth-class at pipeline assembly; credential verification is delegated to the project's chosen identity provider behind a narrow interface.",
+  "interfaces": [
+    {
+      "name": "class selection",
+      "kind": "configuration",
+      "description": "The endpoint's declared class, read from the same metadata the OpenAPI x-auth-class extension publishes."
+    },
+    {
+      "name": "resolved principal",
+      "kind": "request-context",
+      "description": "The identity (user or service principal) the slot resolves, exposed read-only to handlers and observability."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Request pipeline",
+      "kind": "tac",
+      "tacId": "TAC-301-application-api-rest-request-pipeline",
+      "description": "Hosts the slots at the declared position in the middleware order."
+    }
+  ],
+  "tradeoffs": "Exactly four classes is a deliberate constraint: finer-grained per-endpoint policies are expressible as authorisation checks inside handlers, but class membership, enforcement position, and audit obligations stay fixed. Projects needing a fifth class should supersede the auth-model decision record rather than special-casing an endpoint.",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

package/blueprints/application-api-rest/contributions/tacs/tac-303-application-api-rest-contract-surface.json

@@ -0,0 +1,46 @@
+{
+  "tacId": "TAC-303-application-api-rest-contract-surface",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Contract surface: OpenAPI generation, serving, and drift defence",
+  "purpose": "Owns the generated OpenAPI 3.1 document as a build artefact: generation from source, serving at /openapi.json, /openapi.yaml, and /docs, and the three-axis drift validation that keeps implementation and contract provably identical.",
+  "responsibilities": [
+    "Generate the OpenAPI 3.1 document from route definitions and schema annotations at build time; no hand-written parallel spec exists (application-api-rest-REQ-004).",
+    "Serve the generated document and the interactive documentation UI per the declared exposure policy (AC-2104-6).",
+    "Publish per-operation metadata: operationId, schemas, x-auth-class, rate-limit overrides, idempotency requirements.",
+    "Run contract validation in the build: implemented-but-undeclared, declared-but-unimplemented, and type-level schema mismatch each fail the build (application-api-rest-REQ-004, AC-2105-4).",
+    "Drive spec-derived conformance verification so every declared operation is exercised on the request, error, and auth axes (application-api-rest-REQ-015)."
+  ],
+  "internalStructure": "A generator over the same endpoint metadata the pipeline consumes (one source of truth), a validator comparing route table with generated document, and a conformance driver iterating the document at verification time.",
+  "interfaces": [
+    {
+      "name": "generated spec",
+      "kind": "artefact",
+      "description": "The OpenAPI 3.1 document, emitted at build time and served at runtime; the single contract clients and the conformance driver both consume."
+    },
+    {
+      "name": "documentation endpoints",
+      "kind": "http",
+      "description": "/openapi.json, /openapi.yaml, and /docs, exposure-policy controlled."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Resource layer",
+      "kind": "tac",
+      "tacId": "TAC-304-application-api-rest-resource-layer",
+      "description": "Route definitions and representation schemas are the generator's input."
+    },
+    {
+      "name": "Request pipeline",
+      "kind": "tac",
+      "tacId": "TAC-301-application-api-rest-request-pipeline",
+      "description": "Shares the endpoint metadata so declaration and enforcement cannot diverge."
+    }
+  ],
+  "tradeoffs": "Generation from source means the spec's quality ceiling is the annotation discipline in the code; the drift validator is what turns sloppy annotations into build failures instead of quiet documentation rot. The build-time cost of validation buys the absence of a whole defect class.",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

package/blueprints/application-api-rest/contributions/tacs/tac-304-application-api-rest-resource-layer.json

@@ -0,0 +1,46 @@
+{
+  "tacId": "TAC-304-application-api-rest-resource-layer",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Resource layer: routes, representations, and collection conventions",
+  "purpose": "Owns the versioned resource surface: the route inventory under /v1, one representation model per resource class, and the shared collection machinery for pagination, filtering, and sorting so every collection behaves identically.",
+  "responsibilities": [
+    "Maintain the declared route inventory: plural-noun collections, scoped nesting only for genuine 1:N relationships, verb-free paths (application-api-rest-REQ-001).",
+    "Define one representation model per resource class and serialise it under the declared casing and timestamp rules everywhere that class appears (application-api-rest-REQ-002).",
+    "Implement cursor pagination once, as shared machinery every collection endpoint uses: envelope, opaque cursors, write-stability, limit enforcement, opt-in counts (application-api-rest-REQ-007).",
+    "Implement declared-filter and sort parsing once, with strict rejection of unknown parameters, undeclared sort keys, and type-violating values (application-api-rest-REQ-008).",
+    "Carry the version prefix and the deprecation and sunset header behaviour for every version the service still serves (application-api-rest-REQ-003)."
+  ],
+  "internalStructure": "Resource modules (routes plus representation schema plus declared filters and sortable fields) registered against shared collection machinery; the registration data doubles as generator input for the contract surface.",
+  "interfaces": [
+    {
+      "name": "resource registration",
+      "kind": "configuration",
+      "description": "Each resource declares its routes, representation schema, filters, sortable fields, and auth classes in one registration record."
+    },
+    {
+      "name": "collection envelope",
+      "kind": "wire-format",
+      "description": "The pagination envelope (items, next, prev, optional total) every collection response uses."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Request pipeline",
+      "kind": "tac",
+      "tacId": "TAC-301-application-api-rest-request-pipeline",
+      "description": "All resource routes are served through the shared pipeline."
+    },
+    {
+      "name": "Contract surface",
+      "kind": "tac",
+      "tacId": "TAC-303-application-api-rest-contract-surface",
+      "description": "Resource registrations feed the OpenAPI generator."
+    }
+  ],
+  "tradeoffs": "Shared collection machinery constrains exotic per-collection behaviour on purpose: a collection that genuinely cannot paginate by cursor is an explicit decision-record-level exception, not a quiet divergence. The registration record is one more thing to write per resource and is what makes contract generation and strict validation possible.",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

package/blueprints/application-api-rest/contributions/tacs/tac-305-application-api-rest-observability.json

@@ -0,0 +1,40 @@
+{
+  "tacId": "TAC-305-application-api-rest-observability",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Observability: logs, metrics, and traces from one signal model",
+  "purpose": "Owns the three telemetry signals as one coherent model: structured JSON logs, RED metrics with per-class and probe series, and OpenTelemetry-compatible traces, all keyed by the same request id and auth class so any signal pivots to the others.",
+  "responsibilities": [
+    "Emit structured JSON log lines with the base fields, request id, trace id, and per-class completion levels (application-api-rest-REQ-012, application-api-rest-US-2114).",
+    "Record RED metrics per path template and method, per-class counters, duration histograms, and the dedicated probe-outcome series (application-api-rest-US-2115).",
+    "Produce server spans per request with the declared attributes, honour inbound traceparent, and propagate context to downstream calls (application-api-rest-US-2116).",
+    "Apply the redaction rules before any signal leaves the process: no secrets, PII only in redacted form (application-api-rest-REQ-016).",
+    "Keep probe traffic out of info-level logs and endpoint RED series (application-api-rest-REQ-006)."
+  ],
+  "internalStructure": "A request-telemetry context created by the pipeline's edge middleware and enriched as the request progresses; log, metric, and span emitters read the same context so field values never disagree across signals.",
+  "interfaces": [
+    {
+      "name": "telemetry context",
+      "kind": "request-context",
+      "description": "Request id, trace context, auth class, path template, and timing, shared by all three emitters."
+    },
+    {
+      "name": "signal exporters",
+      "kind": "configuration",
+      "description": "Where logs, metrics, and traces go is deployment configuration; the shapes emitted are contract."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Request pipeline",
+      "kind": "tac",
+      "tacId": "TAC-301-application-api-rest-request-pipeline",
+      "description": "The pipeline creates and finalises the telemetry context per request."
+    }
+  ],
+  "tradeoffs": "One shared context adds a small per-request allocation and buys signal agreement: the duration in the log line, the histogram sample, and the span timing come from the same clock reads. Emitting three signals is redundant by design; each answers a question the others answer badly.",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}