rcf-lite 0.12.0 → 0.13.0

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

@@ -0,0 +1,72 @@
+{
+  "usId": "application-api-rest-US-2109",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-007",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Cursor pagination with a navigable envelope and enforced limits",
+  "asA": "API consumer walking large collections",
+  "iWant": "stable cursors, next and prev links, and predictable page sizes on every collection",
+  "soThat": "I can traverse any collection completely and efficiently without skipped or duplicated items",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2109-1",
+      "description": "Every collection endpoint accepts ?cursor= and ?limit= and responds with the declared pagination envelope carrying items, next, and prev.",
+      "given": "any collection endpoint",
+      "when": "a page is requested with cursor and limit",
+      "then": "the response conforms to the pagination envelope with items, next, and prev fields",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2109-2",
+      "description": "next is null on the last page and prev is null on the first; following next repeatedly from the first page visits every item exactly once.",
+      "given": "a collection with a known item set spanning multiple pages",
+      "when": "the collection is walked via next from the first page",
+      "then": "every item appears exactly once and the final page's next is null",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2109-3",
+      "description": "Cursors are opaque: they carry no client-decodable positional semantics the client is invited to construct, and a tampered cursor is rejected with 400 and a problem-details body.",
+      "given": "a syntactically altered cursor value",
+      "when": "it is submitted",
+      "then": "the service responds 400 with the declared error envelope rather than best-effort interpretation",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2109-4",
+      "description": "Pagination is write-stable: items present in the collection for the whole traversal are neither skipped nor duplicated when concurrent inserts and deletes occur mid-walk.",
+      "given": "a traversal in progress while other clients insert and delete items",
+      "when": "the walk completes",
+      "then": "every item that existed throughout appears exactly once",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2109-5",
+      "description": "The declared maximum limit is enforced: a request exceeding it receives 400 with a problem-details body naming the maximum, and a request without a limit receives the declared default page size.",
+      "given": "requests with an oversized limit and with no limit",
+      "when": "each is submitted",
+      "then": "the oversized request receives 400 naming the maximum; the limitless request returns the default page size",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2109-6",
+      "description": "Total counts are off by default and returned only when explicitly requested via the documented parameter, so the expensive count is never paid unknowingly.",
+      "given": "a collection request without the count parameter and one with it",
+      "when": "both responses are compared",
+      "then": "only the explicit request carries the total, per the envelope's documented count field",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-304-application-api-rest-resource-layer"
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,72 @@
+{
+  "usId": "application-api-rest-US-2110",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-008",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Documented filters, one sort convention, and strict rejection of unknown parameters",
+  "asA": "API consumer querying collections",
+  "iWant": "declared filter names, a single sort syntax, and hard errors on anything the endpoint does not understand",
+  "soThat": "my queries do exactly what they say or fail loudly, never silently returning the wrong result set",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2110-1",
+      "description": "Every collection endpoint's filter parameters are declared in the generated spec with their types and accepted values; no undocumented filter is honoured.",
+      "given": "the generated spec entry for a collection endpoint",
+      "when": "its declared filters are compared with the parameters the implementation honours",
+      "then": "the sets are identical",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2110-2",
+      "description": "Sorting uses ?sort=field,-field2: comma-separated keys, leading minus for descending, applied in declared key order.",
+      "given": "a collection with sortable fields",
+      "when": "?sort=fieldA,-fieldB is requested",
+      "then": "results order by fieldA ascending then fieldB descending",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2110-3",
+      "description": "A request carrying an unknown query parameter is rejected with 400 and a problem-details body naming the unknown parameter, on every endpoint.",
+      "given": "any endpoint",
+      "when": "a request carries an undeclared query parameter",
+      "then": "the service responds 400 with the declared error envelope naming the parameter, and no handler logic runs",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2110-4",
+      "description": "A sort key that is not declared sortable for the resource is rejected with 400 and a problem-details body naming the key and the declared sortable set.",
+      "given": "a collection endpoint",
+      "when": "?sort= names an undeclared key",
+      "then": "the service responds 400 with the error envelope naming the key and the sortable fields",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2110-5",
+      "description": "A filter value violating the parameter's declared type or format is rejected with 400 and a problem-details body naming the parameter and expected type, never coerced silently.",
+      "given": "a declared filter of a specific type",
+      "when": "a value of the wrong type is submitted",
+      "then": "the service responds 400 with the error envelope naming parameter and expected type",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2110-6",
+      "description": "Filters, sorting, and pagination compose: a filtered, sorted collection paginates correctly with the filter and sort preserved across cursor navigation.",
+      "given": "a filtered and sorted multi-page query",
+      "when": "the next cursor is followed",
+      "then": "subsequent pages honour the same filter and sort without restating them incorrectly or losing them",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-304-application-api-rest-resource-layer"
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,72 @@
+{
+  "usId": "application-api-rest-US-2111",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-009",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Problem details everywhere: one error shape on every failure path",
+  "asA": "API consumer building error handling once",
+  "iWant": "every error response, planned or unplanned, to carry the same RFC 7807 envelope",
+  "soThat": "my client renders and reacts to any failure from structure, never from guessing at ad-hoc bodies",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2111-1",
+      "description": "Every 4xx and 5xx response body is an RFC 7807 problem-details object carrying type, title, status, detail, and instance, served as application/problem+json.",
+      "given": "any error response from any endpoint",
+      "when": "the body and content type are inspected",
+      "then": "the body carries the five base fields and the content type is application/problem+json",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2111-2",
+      "description": "Service-specific extension fields on the envelope are declared in the generated spec; no error response carries undeclared extensions.",
+      "given": "the generated spec's problem-details schema and observed error responses",
+      "when": "extension fields are compared against the declaration",
+      "then": "every observed extension is declared",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2111-3",
+      "description": "The status field inside the envelope always equals the HTTP status code of the response carrying it.",
+      "given": "any error response",
+      "when": "the body's status field and the HTTP status line are compared",
+      "then": "they are equal",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2111-4",
+      "description": "4xx responses carry actionable detail (what was wrong with the request and how to correct it); 5xx responses carry the instance id for support without leaking stack traces, queries, or internal paths.",
+      "given": "a 4xx and a 5xx response",
+      "when": "their detail fields are read",
+      "then": "the 4xx names the client-side correction; the 5xx exposes the correlation instance and no internals",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2111-5",
+      "description": "Unhandled exceptions are converted to a 500 problem-details response by a final error middleware; no path returns a framework default error page or bare stack output.",
+      "given": "a handler that throws an unexpected exception",
+      "when": "the request is submitted",
+      "then": "the response is a 500 with the declared envelope, not a framework default body",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2111-6",
+      "description": "Errors raised before routing completes (unknown path, method not allowed, oversized body, unparseable JSON) also carry the envelope, proving it holds outside handler code.",
+      "given": "requests triggering pre-routing failures: unknown path, wrong method, oversized body, malformed JSON",
+      "when": "each response is inspected",
+      "then": "each carries the declared problem-details envelope with the appropriate 4xx status",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-301-application-api-rest-request-pipeline"
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,72 @@
+{
+  "usId": "application-api-rest-US-2112",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-010",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Idempotency keys: retries replay, duplicates never apply twice",
+  "asA": "API consumer retrying over an unreliable network",
+  "iWant": "my retried mutation to return the original outcome instead of applying again",
+  "soThat": "network failures cost me a retry, never a duplicate side effect",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2112-1",
+      "description": "The project declares which verb and resource-class combinations require an Idempotency-Key; the declaration is published in the generated spec per operation.",
+      "given": "the generated OpenAPI document",
+      "when": "operations on non-safe verbs are inspected",
+      "then": "each declares whether Idempotency-Key is required, and every duplicate-harmful operation declares it required",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2112-2",
+      "description": "An operation declared key-required rejects a request without the header: 400 with a problem-details body naming the missing header.",
+      "given": "a key-required operation",
+      "when": "a request without Idempotency-Key is submitted",
+      "then": "the service responds 400 with the error envelope naming the header",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2112-3",
+      "description": "Repeating a request with the same key and identical body within the TTL returns the original response (same status, same body) and does not re-apply the side effect.",
+      "given": "a completed keyed mutation",
+      "when": "the identical request is repeated within the TTL",
+      "then": "the original response is replayed and exactly one side effect exists",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2112-4",
+      "description": "Reusing a key with a different request body is rejected with 422 and a problem-details body naming the key conflict, protecting against accidental key sharing.",
+      "given": "a key already used for one request body",
+      "when": "the same key arrives with a different body within the TTL",
+      "then": "the service responds 422 with the error envelope naming the conflict",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2112-5",
+      "description": "A retry arriving while the original request is still in flight receives 409 with a problem-details body indicating processing is in progress, rather than triggering a concurrent second application.",
+      "given": "a keyed request still executing",
+      "when": "the same key and body arrive concurrently",
+      "then": "the second request receives 409 with the error envelope and the side effect applies exactly once",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2112-6",
+      "description": "The de-duplication cache honours its declared TTL: within it replays occur, after it a reused key is treated as a fresh request, and the TTL value is documented.",
+      "given": "the declared TTL",
+      "when": "a keyed request is repeated inside and after the TTL window",
+      "then": "the inside repeat replays; the after repeat executes as new; the TTL matches its documentation",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-301-application-api-rest-request-pipeline"
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,73 @@
+{
+  "usId": "application-api-rest-US-2113",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-011",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Class-scoped rate limits with mechanical back-off signals",
+  "asA": "platform operator protecting the service from overload",
+  "iWant": "each auth class limited on its own budget with standards-shaped 429 responses",
+  "soThat": "abusive anonymous traffic cannot starve users, and well-behaved clients back off without custom logic",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2113-1",
+      "description": "Each of the four auth classes has a declared rate limit, and requests are counted against the limit of the endpoint's class.",
+      "given": "the declared per-class limits",
+      "when": "traffic flows to endpoints of each class",
+      "then": "each request decrements its class's budget and no other's",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2113-2",
+      "description": "A request over its limit receives 429 with a Retry-After header and a problem-details body naming the limit and window.",
+      "given": "a caller exceeding its class limit",
+      "when": "the next request arrives",
+      "then": "the response is 429 with Retry-After and the error envelope naming limit and window",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2113-3",
+      "description": "Limits are keyed per caller within the class (per identity for user and admin, per service principal for service, per client address for public), so one hot caller cannot exhaust the class for everyone.",
+      "given": "two callers of the same class, one at its limit",
+      "when": "the second caller sends a request",
+      "then": "the second caller is served while the first receives 429",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2113-4",
+      "description": "A per-endpoint override of the class default is supported, declared in the spec alongside the endpoint, and enforcement follows the override.",
+      "given": "an endpoint declaring a rate-limit override",
+      "when": "traffic exceeds the override but not the class default (or vice versa)",
+      "then": "enforcement follows the declared override exactly",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2113-5",
+      "description": "Waiting out Retry-After restores service: a request after the advertised delay succeeds, proving the advertised value is honest.",
+      "given": "a 429 with Retry-After",
+      "when": "the caller waits the advertised delay and retries",
+      "then": "the retry succeeds",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2113-6",
+      "description": "Rate-limit rejections are visible in observability: 429s are counted in the endpoint's RED metrics and per-class counters without emitting per-rejection error-level log noise.",
+      "given": "a burst producing 429s",
+      "when": "metrics and logs are inspected",
+      "then": "the 429s appear in RED and class counters, and no error-level log line per rejection exists",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-301-application-api-rest-request-pipeline",
+    "TAC-302-application-api-rest-auth-middleware"
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,63 @@
+{
+  "usId": "application-api-rest-US-2114",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-012",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Structured logs: JSON lines, request-scoped correlation, declared levels",
+  "asA": "on-call engineer diagnosing a production incident",
+  "iWant": "machine-parseable logs where every request-scoped line carries its correlation ids",
+  "soThat": "I can reconstruct any request's story with one query instead of reading prose",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2114-1",
+      "description": "Every log line is a single JSON object with at minimum timestamp, level, message, and service name; no multi-line or prose-format lines are emitted.",
+      "given": "log output under normal and error traffic",
+      "when": "each line is parsed as JSON",
+      "then": "every line parses and carries the four base fields",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2114-2",
+      "description": "Every request-scoped log line carries the request id and, when tracing is active, the trace id.",
+      "given": "a request producing multiple log lines",
+      "when": "the lines are filtered by the request id",
+      "then": "every line the request produced appears, each also carrying the trace id when a trace context existed",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2114-3",
+      "description": "The declared log level per auth class is honoured: request completion lines are emitted at the class's declared level, and level configuration changes take effect without a code change.",
+      "given": "the declared per-class log levels",
+      "when": "traffic flows through each class",
+      "then": "completion lines appear at the declared level per class",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2114-4",
+      "description": "Request completion lines carry method, path template, status, duration, and auth class, so traffic questions are answerable from logs alone.",
+      "given": "a completed request",
+      "when": "its completion line is read",
+      "then": "method, path template, status, duration, and auth class are present",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2114-5",
+      "description": "Log output honours the redaction rules of application-api-rest-REQ-016: no secrets and no unredacted PII at any level, verified against a request deliberately carrying both.",
+      "given": "a request carrying a bearer token and personal data",
+      "when": "all log output for that request is scanned",
+      "then": "the token never appears and personal data appears only in redacted form",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-305-application-api-rest-observability"
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,63 @@
+{
+  "usId": "application-api-rest-US-2115",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-012",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "RED metrics per endpoint with per-class and probe-outcome series",
+  "asA": "platform operator watching service health",
+  "iWant": "rate, error, and duration measured per endpoint, plus per-class counters and probe outcomes",
+  "soThat": "dashboards and alerts answer is it up, is it erroring, is it slow for every endpoint without instrumenting by hand",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2115-1",
+      "description": "Request rate, error rate, and duration are recorded per endpoint, labelled by path template (never raw paths with ids), method, and status class.",
+      "given": "traffic across several endpoints",
+      "when": "the metrics endpoint or exporter output is read",
+      "then": "RED series exist per path template and method, and no label carries a raw resource id",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2115-2",
+      "description": "Duration is recorded as a histogram with declared buckets so latency percentiles are computable, not as an average-only gauge.",
+      "given": "recorded duration metrics",
+      "when": "the metric type is inspected",
+      "then": "durations are histograms with the declared bucket boundaries",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2115-3",
+      "description": "Per-auth-class request counters exist, so each class's traffic volume and error share are independently visible.",
+      "given": "traffic across the four auth classes",
+      "when": "per-class counters are read",
+      "then": "each class's requests and errors are counted under its own label",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2115-4",
+      "description": "Probe outcomes are recorded under a dedicated metric per probe with success and failure counts, separate from endpoint RED series per AC-2108-6.",
+      "given": "steady probe traffic including induced readiness failures",
+      "when": "the probe metric is read",
+      "then": "per-probe success and failure counts reflect the induced states",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2115-5",
+      "description": "Every declared business endpoint appears in RED metrics after first traffic; there is no unmeasured endpoint class.",
+      "given": "one request to every declared endpoint",
+      "when": "the metric series are enumerated",
+      "then": "every declared endpoint's path template appears",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-305-application-api-rest-observability"
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,63 @@
+{
+  "usId": "application-api-rest-US-2116",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-012",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "OpenTelemetry-compatible traces with declared span attributes",
+  "asA": "on-call engineer following a slow request across services",
+  "iWant": "a span per request carrying auth class, resource id, and response status, linked to downstream spans",
+  "soThat": "latency and failure are attributable to a hop, not to the system in general",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2116-1",
+      "description": "Every handled request produces an OpenTelemetry-compatible server span named by method and path template, with correct start, end, and status.",
+      "given": "a handled request",
+      "when": "exported spans are inspected",
+      "then": "a server span exists with the method and path template name and timing that brackets the request",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2116-2",
+      "description": "Spans carry the declared attributes: auth class, resource id where the route binds one, response status code, and the request id.",
+      "given": "a request to a resource endpoint",
+      "when": "its span attributes are read",
+      "then": "auth class, resource id, status code, and request id are present",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2116-3",
+      "description": "Inbound trace context (traceparent) is honoured: the server span joins the caller's trace rather than starting a fresh one.",
+      "given": "a request carrying a valid traceparent header",
+      "when": "the resulting span is inspected",
+      "then": "it carries the inbound trace id as its parent context",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2116-4",
+      "description": "Downstream calls made on behalf of a request (database, cache, HTTP) produce child spans within the request's trace with the trace context propagated onward.",
+      "given": "a request whose handler calls a downstream dependency",
+      "when": "the trace is assembled",
+      "then": "the downstream call appears as a child span and the dependency received the propagated context",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2116-5",
+      "description": "Error responses mark their span status as error with the problem type recorded, so failed requests are findable by span status alone.",
+      "given": "a request ending in a 5xx",
+      "when": "its span is inspected",
+      "then": "span status is error and the problem type is recorded as an attribute",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-305-application-api-rest-observability"
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,64 @@
+{
+  "usId": "application-api-rest-US-2117",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-013",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "One request id from edge to every hop",
+  "asA": "support engineer holding a single id from a bug report",
+  "iWant": "that id assigned or accepted at the edge, echoed to the client, and threaded through every downstream call",
+  "soThat": "one identifier retrieves the complete story of one user action",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2117-1",
+      "description": "A request arriving with a valid X-Request-Id keeps it: the same value appears in the response header and in every request-scoped log line.",
+      "given": "a request carrying X-Request-Id",
+      "when": "the response and logs are inspected",
+      "then": "the inbound value is echoed in the response and present on every request-scoped log line",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2117-2",
+      "description": "A request arriving without X-Request-Id is assigned one at the edge before any other middleware runs, and the assigned value is echoed in the response.",
+      "given": "a request with no X-Request-Id",
+      "when": "the response is inspected",
+      "then": "a generated id in the documented format is present in the response header",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2117-3",
+      "description": "An inbound X-Request-Id failing the documented format or length constraints is replaced with a generated id rather than propagated, so hostile header values never flow into logs and downstream systems.",
+      "given": "a request with an oversized or malformed X-Request-Id",
+      "when": "the response and logs are inspected",
+      "then": "a fresh generated id is used and the malformed inbound value is not propagated",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2117-4",
+      "description": "Every downstream call made on behalf of a request carries the request id onward in its headers or protocol equivalent.",
+      "given": "a handler calling a downstream HTTP dependency",
+      "when": "the outbound request is captured",
+      "then": "it carries the same X-Request-Id value",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2117-5",
+      "description": "Error responses carry the request id in both the response header and the problem-details instance field, so a failure report contains its own correlation handle.",
+      "given": "a request ending in an error",
+      "when": "the response is inspected",
+      "then": "the header and the envelope's instance field both carry the request id",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-301-application-api-rest-request-pipeline",
+    "TAC-305-application-api-rest-observability"
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}