rcf-lite 0.12.0 → 0.13.0

package/blueprints/application-api-rest/assets/samples/request-response-pairs.md

@@ -0,0 +1,204 @@
+# Sample request-response pairs per verb class
+
+Reference realisations of the wire contract (application-api-rest-REQ-002, application-api-rest-REQ-007, application-api-rest-REQ-009, application-api-rest-REQ-010) using the illustrative `widgets` resource from the OpenAPI skeleton. The shapes are normative; the resource is not. All timestamps RFC-3339 UTC, all properties camelCase, every response with an explicit Content-Type.
+
+## GET, collection page (filtered, sorted, paginated)
+
+```
+GET /v1/widgets?status=active&sort=name,-createdAt&limit=2 HTTP/1.1
+Authorization: Bearer <token>
+```
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+X-Request-Id: 7f3a2c9e-4b1d-4e8a-9c6f-2d5b8e1a0f47
+
+{
+  "items": [
+    {
+      "id": "wgt_01j5xq",
+      "name": "Alpha widget",
+      "status": "active",
+      "createdAt": "2026-08-19T09:14:07Z",
+      "updatedAt": "2026-08-19T09:14:07Z"
+    },
+    {
+      "id": "wgt_01j5xr",
+      "name": "Beta widget",
+      "status": "active",
+      "createdAt": "2026-08-18T16:02:33Z",
+      "updatedAt": "2026-08-19T08:41:12Z"
+    }
+  ],
+  "next": "b3BhcXVlLWN1cnNvci0y",
+  "prev": null
+}
+```
+
+## GET, single resource
+
+```
+GET /v1/widgets/wgt_01j5xq HTTP/1.1
+Authorization: Bearer <token>
+```
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "id": "wgt_01j5xq",
+  "name": "Alpha widget",
+  "status": "active",
+  "createdAt": "2026-08-19T09:14:07Z",
+  "updatedAt": "2026-08-19T09:14:07Z"
+}
+```
+
+## POST, creation with idempotency key
+
+```
+POST /v1/widgets HTTP/1.1
+Authorization: Bearer <token>
+Content-Type: application/json
+Idempotency-Key: 0d9f6a7e-create-alpha
+
+{ "name": "Alpha widget" }
+```
+
+```
+HTTP/1.1 201 Created
+Content-Type: application/json
+Location: /v1/widgets/wgt_01j5xq
+
+{
+  "id": "wgt_01j5xq",
+  "name": "Alpha widget",
+  "status": "active",
+  "createdAt": "2026-08-19T09:14:07Z",
+  "updatedAt": "2026-08-19T09:14:07Z"
+}
+```
+
+Retried identically within the TTL: the same 201 body replays, nothing applies twice (AC-2112-3). Same key, different body: 422 problem details (AC-2112-4).
+
+## PATCH, partial update returning the result
+
+```
+PATCH /v1/widgets/wgt_01j5xq HTTP/1.1
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{ "status": "archived" }
+```
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "id": "wgt_01j5xq",
+  "name": "Alpha widget",
+  "status": "archived",
+  "createdAt": "2026-08-19T09:14:07Z",
+  "updatedAt": "2026-08-19T11:20:45Z"
+}
+```
+
+## DELETE, idempotent removal
+
+```
+DELETE /v1/widgets/wgt_01j5xq HTTP/1.1
+Authorization: Bearer <token>
+```
+
+```
+HTTP/1.1 204 No Content
+```
+
+Repeated DELETE of the same id: 404 with problem details is acceptable and documented; 500 is not.
+
+## Error shapes
+
+Validation failure (unknown query parameter, AC-2110-3):
+
+```
+HTTP/1.1 400 Bad Request
+Content-Type: application/problem+json
+
+{
+  "type": "https://example.com/problems/unknown-parameter",
+  "title": "Unknown query parameter",
+  "status": 400,
+  "detail": "Parameter 'colour' is not declared for this endpoint. Declared parameters: cursor, limit, includeTotal, status, sort.",
+  "instance": "urn:request:7f3a2c9e-4b1d-4e8a-9c6f-2d5b8e1a0f47"
+}
+```
+
+Auth failure on a user-class endpoint (AC-2106-5):
+
+```
+HTTP/1.1 401 Unauthorized
+Content-Type: application/problem+json
+
+{
+  "type": "https://example.com/problems/unauthenticated",
+  "title": "Authentication required",
+  "status": 401,
+  "detail": "Provide a valid bearer token or session.",
+  "instance": "urn:request:2b8e1a0f-9c6f-4e8a-4b1d-7f3a2c9e5d47"
+}
+```
+
+Rate limit (application-api-rest-REQ-011):
+
+```
+HTTP/1.1 429 Too Many Requests
+Content-Type: application/problem+json
+Retry-After: 12
+
+{
+  "type": "https://example.com/problems/rate-limited",
+  "title": "Rate limit exceeded",
+  "status": 429,
+  "detail": "User-class limit of 100 requests per 60s window exceeded. Retry after 12 seconds.",
+  "instance": "urn:request:9c6f2d5b-8e1a-0f47-4b1d-7f3a2c9e4e8a"
+}
+```
+
+Server failure (no internals leaked, AC-2111-4):
+
+```
+HTTP/1.1 500 Internal Server Error
+Content-Type: application/problem+json
+
+{
+  "type": "https://example.com/problems/internal",
+  "title": "Internal server error",
+  "status": 500,
+  "detail": "An unexpected condition prevented the request from completing. Quote the instance id to support.",
+  "instance": "urn:request:4e8a9c6f-2d5b-4b1d-8e1a-7f3a2c9e0f47"
+}
+```
+
+## Probe shapes (application-api-rest-REQ-006)
+
+```
+GET /healthz/ready HTTP/1.1
+```
+
+Degraded:
+
+```
+HTTP/1.1 503 Service Unavailable
+Content-Type: application/json
+
+{
+  "status": "failing",
+  "checks": [
+    { "name": "database", "status": "ok" },
+    { "name": "cache", "status": "failing", "detail": "connect timeout after 250ms" }
+  ]
+}
+```

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

@@ -0,0 +1,265 @@
+{
+  "slug": "application-api-rest",
+  "version": "1.0.0",
+  "category": "application",
+  "contributions": [
+    {
+      "id": "application-api-rest-REQ-001",
+      "kind": "req",
+      "path": "requirements/application-api-rest-req-001.json"
+    },
+    {
+      "id": "application-api-rest-REQ-002",
+      "kind": "req",
+      "path": "requirements/application-api-rest-req-002.json"
+    },
+    {
+      "id": "application-api-rest-REQ-003",
+      "kind": "req",
+      "path": "requirements/application-api-rest-req-003.json"
+    },
+    {
+      "id": "application-api-rest-REQ-004",
+      "kind": "req",
+      "path": "requirements/application-api-rest-req-004.json"
+    },
+    {
+      "id": "application-api-rest-REQ-005",
+      "kind": "req",
+      "path": "requirements/application-api-rest-req-005.json"
+    },
+    {
+      "id": "application-api-rest-REQ-006",
+      "kind": "req",
+      "path": "requirements/application-api-rest-req-006.json"
+    },
+    {
+      "id": "application-api-rest-REQ-007",
+      "kind": "req",
+      "path": "requirements/application-api-rest-req-007.json"
+    },
+    {
+      "id": "application-api-rest-REQ-008",
+      "kind": "req",
+      "path": "requirements/application-api-rest-req-008.json"
+    },
+    {
+      "id": "application-api-rest-REQ-009",
+      "kind": "req",
+      "path": "requirements/application-api-rest-req-009.json"
+    },
+    {
+      "id": "application-api-rest-REQ-010",
+      "kind": "req",
+      "path": "requirements/application-api-rest-req-010.json"
+    },
+    {
+      "id": "application-api-rest-REQ-011",
+      "kind": "req",
+      "path": "requirements/application-api-rest-req-011.json"
+    },
+    {
+      "id": "application-api-rest-REQ-012",
+      "kind": "req",
+      "path": "requirements/application-api-rest-req-012.json"
+    },
+    {
+      "id": "application-api-rest-REQ-013",
+      "kind": "req",
+      "path": "requirements/application-api-rest-req-013.json"
+    },
+    {
+      "id": "application-api-rest-REQ-014",
+      "kind": "req",
+      "path": "requirements/application-api-rest-req-014.json"
+    },
+    {
+      "id": "application-api-rest-REQ-015",
+      "kind": "req",
+      "path": "requirements/application-api-rest-req-015.json"
+    },
+    {
+      "id": "application-api-rest-REQ-016",
+      "kind": "req",
+      "path": "requirements/application-api-rest-req-016.json"
+    },
+    {
+      "id": "application-api-rest-US-2101",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2101.json"
+    },
+    {
+      "id": "application-api-rest-US-2102",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2102.json"
+    },
+    {
+      "id": "application-api-rest-US-2103",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2103.json"
+    },
+    {
+      "id": "application-api-rest-US-2104",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2104.json"
+    },
+    {
+      "id": "application-api-rest-US-2105",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2105.json"
+    },
+    {
+      "id": "application-api-rest-US-2106",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2106.json"
+    },
+    {
+      "id": "application-api-rest-US-2107",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2107.json"
+    },
+    {
+      "id": "application-api-rest-US-2108",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2108.json"
+    },
+    {
+      "id": "application-api-rest-US-2109",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2109.json"
+    },
+    {
+      "id": "application-api-rest-US-2110",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2110.json"
+    },
+    {
+      "id": "application-api-rest-US-2111",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2111.json"
+    },
+    {
+      "id": "application-api-rest-US-2112",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2112.json"
+    },
+    {
+      "id": "application-api-rest-US-2113",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2113.json"
+    },
+    {
+      "id": "application-api-rest-US-2114",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2114.json"
+    },
+    {
+      "id": "application-api-rest-US-2115",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2115.json"
+    },
+    {
+      "id": "application-api-rest-US-2116",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2116.json"
+    },
+    {
+      "id": "application-api-rest-US-2117",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2117.json"
+    },
+    {
+      "id": "application-api-rest-US-2118",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2118.json"
+    },
+    {
+      "id": "application-api-rest-US-2119",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2119.json"
+    },
+    {
+      "id": "application-api-rest-US-2120",
+      "kind": "us",
+      "path": "user-stories/application-api-rest-us-2120.json"
+    },
+    {
+      "id": "TAC-301-application-api-rest-request-pipeline",
+      "kind": "tac",
+      "path": "tacs/tac-301-application-api-rest-request-pipeline.json"
+    },
+    {
+      "id": "TAC-302-application-api-rest-auth-middleware",
+      "kind": "tac",
+      "path": "tacs/tac-302-application-api-rest-auth-middleware.json"
+    },
+    {
+      "id": "TAC-303-application-api-rest-contract-surface",
+      "kind": "tac",
+      "path": "tacs/tac-303-application-api-rest-contract-surface.json"
+    },
+    {
+      "id": "TAC-304-application-api-rest-resource-layer",
+      "kind": "tac",
+      "path": "tacs/tac-304-application-api-rest-resource-layer.json"
+    },
+    {
+      "id": "TAC-305-application-api-rest-observability",
+      "kind": "tac",
+      "path": "tacs/tac-305-application-api-rest-observability.json"
+    },
+    {
+      "id": "TAC-306-application-api-rest-operability",
+      "kind": "tac",
+      "path": "tacs/tac-306-application-api-rest-operability.json"
+    },
+    {
+      "id": "ADR-301-application-api-rest-error-envelope",
+      "kind": "adr",
+      "path": "adrs/adr-301-application-api-rest-error-envelope.json",
+      "scope": "global",
+      "topic": "errorEnvelope"
+    },
+    {
+      "id": "ADR-302-application-api-rest-auth-model",
+      "kind": "adr",
+      "path": "adrs/adr-302-application-api-rest-auth-model.json",
+      "scope": "global",
+      "topic": "authModel"
+    },
+    {
+      "id": "ADR-303-application-api-rest-api-versioning",
+      "kind": "adr",
+      "path": "adrs/adr-303-application-api-rest-api-versioning.json",
+      "scope": "global",
+      "topic": "apiVersioning"
+    },
+    {
+      "id": "ADR-304-application-api-rest-logging",
+      "kind": "adr",
+      "path": "adrs/adr-304-application-api-rest-logging.json",
+      "scope": "global",
+      "topic": "logging"
+    },
+    {
+      "id": "ADR-305-application-api-rest-pagination",
+      "kind": "adr",
+      "path": "adrs/adr-305-application-api-rest-pagination.json"
+    },
+    {
+      "id": "ADR-306-application-api-rest-idempotency",
+      "kind": "adr",
+      "path": "adrs/adr-306-application-api-rest-idempotency.json"
+    },
+    {
+      "id": "ADR-307-application-api-rest-openapi-generation",
+      "kind": "adr",
+      "path": "adrs/adr-307-application-api-rest-openapi-generation.json"
+    },
+    {
+      "id": "ADR-308-application-api-rest-rate-limiting",
+      "kind": "adr",
+      "path": "adrs/adr-308-application-api-rest-rate-limiting.json"
+    }
+  ]
+}

package/blueprints/application-api-rest/contributions/adrs/adr-301-application-api-rest-error-envelope.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-301-application-api-rest-error-envelope",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "RFC 7807 problem details as the error shape the service produces",
+  "context": "Every error the service emits is part of its wire contract, including the failures nobody plans: auth rejections, rate limits, malformed input, unhandled exceptions. The wire error shape is a whole-project decision with room for exactly one answer, shared with whatever consumes the API; this record is the producer half. A client-tier blueprint applied to the same project contributes its own decision on the same topic, and blueprint composition surfaces that pairing for the operator to reconcile at add time. That surfacing is intended.",
+  "decision": "The service emits RFC 7807 problem details (type, title, status, detail, instance, plus declared service extensions) as application/problem+json on every 4xx and 5xx, produced by the terminal error boundary in the request pipeline (TAC-301) so no failure path can bypass it. The instance field carries the request id. Extension fields are declared in the generated OpenAPI document; undeclared extensions are contract drift.",
+  "consequences": "Clients build error handling once against one shape. Error responses become verifiable contract surface: the conformance run (application-api-rest-REQ-015) asserts the envelope on every declared operation's failure paths. Composing with a client-tier blueprint raises a deliberate conflict on this topic; the expected resolution is one project-level ADR adopting RFC 7807 end to end, superseding both halves.",
+  "alternativesConsidered": [
+    {
+      "name": "Bespoke error schema",
+      "summary": "Design a service-specific error object with exactly the fields the project wants.",
+      "reasonNotChosen": "Re-derives RFC 7807 minus the standardisation: no off-the-shelf client handling, no problem-type registry discipline, one more thing to document from scratch."
+    },
+    {
+      "name": "Status code plus message string",
+      "summary": "Return { \"error\": \"...\" } with the HTTP status carrying the semantics.",
+      "reasonNotChosen": "Unstructured messages force clients to parse prose, cannot carry correlation or type information, and drift per endpoint the moment two handlers phrase the same failure differently."
+    }
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

package/blueprints/application-api-rest/contributions/adrs/adr-302-application-api-rest-auth-model.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-302-application-api-rest-auth-model",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Four declared auth classes enforced by middleware as the service's authentication model",
+  "context": "A project has one authentication model; endpoints, clients, and operators all reason against it. The server half of that model must make every endpoint's auth posture declared, enumerable, and enforced in one place. A client-tier blueprint applied to the same project contributes its own decision on this topic (how the client authenticates and holds session), and blueprint composition surfaces the pairing at add time for the operator to reconcile into one project-level model. That surfacing is intended.",
+  "decision": "Every endpoint belongs to exactly one of four auth classes: public (no auth processed, rate-limited), user (session or bearer token, identity resolved), admin (user plus admin role, elevated limits, audit-logged), and service (mTLS or signed request, service principal, separate limits, audit-logged). Class membership is declared in the OpenAPI x-auth-class extension, enforced by the class's middleware slot (TAC-302) before handler code runs, and an undeclared endpoint fails contract validation. User-facing credential transport defaults to bearer tokens over TLS, with cookie-based sessions an accepted variant where a browser client owns the session; the project-level reconciliation with the client tier picks one.",
+  "consequences": "The auth posture of the whole surface is auditable by reading the generated spec. Forgetting auth on an endpoint is a build failure, not a penetration-test finding. Rate limits and audit logging attach to classes for free. Composing with a client-tier blueprint deliberately conflicts on this topic; the expected resolution is one project-level ADR fixing the credential transport (bearer or cookie session) and mapping the client's session model onto these four classes.",
+  "alternativesConsidered": [
+    {
+      "name": "Per-endpoint auth annotations without classes",
+      "summary": "Each endpoint declares its own middleware stack of auth requirements.",
+      "reasonNotChosen": "Infinite postures means no enumerable audit story; every endpoint is a bespoke security review, and rate limiting and audit logging cannot attach to anything stable."
+    },
+    {
+      "name": "Gateway-terminated auth only",
+      "summary": "Trust an API gateway to authenticate and pass identity headers inward.",
+      "reasonNotChosen": "Leaves the service naked against direct traffic and misconfigured gateways; defence-in-depth requires the service to enforce its own classes even when a gateway also does."
+    }
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

package/blueprints/application-api-rest/contributions/adrs/adr-303-application-api-rest-api-versioning.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-303-application-api-rest-api-versioning",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Major version in the URL path as the project's API versioning strategy",
+  "context": "Versioning strategy is a whole-project decision: clients, caches, gateways, documentation, and support all key on it, and two strategies on one surface is chaos. The candidates are path versioning, header versioning, media-type versioning, and no versioning with additive-only evolution.",
+  "decision": "The major version rides in the URL path (/v1/...). Breaking changes mint a new major version; within a version, evolution is strictly additive. Deprecated versions announce retirement with Deprecation and Sunset headers on every response, the drop policy (notice period, post-drop 410 with successor pointer) is documented contract, and probe and documentation endpoints live outside the version prefix because they describe the deployment, not the contract (application-api-rest-REQ-003, application-api-rest-US-2103).",
+  "consequences": "The version is visible in every log line, cache key, and copied URL, which makes support and traffic attribution trivial. Running two majors side by side is straightforward routing. The cost is URL churn at major bumps and the temptation to never bump; the sunset machinery exists precisely to make bumps survivable, and the additive-only rule keeps them rare.",
+  "alternativesConsidered": [
+    {
+      "name": "Header or media-type versioning",
+      "summary": "Negotiate the version via a custom header or vendored media type, keeping URLs stable.",
+      "reasonNotChosen": "Invisible in logs, cache keys, browser tooling, and shared links; every debugging session starts by asking which version the client actually requested."
+    },
+    {
+      "name": "No explicit version, additive-only forever",
+      "summary": "One unversioned surface that never breaks.",
+      "reasonNotChosen": "A credible discipline until the first genuinely breaking change, at which point there is no mechanism to ship it; the strategy has to exist before it is needed."
+    }
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-304-application-api-rest-logging",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Structured JSON lines with request-scoped correlation as the project's primary logging shape",
+  "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.",
+  "alternativesConsidered": [
+    {
+      "name": "Human-readable prose lines",
+      "summary": "Classic formatted log lines optimised for tailing.",
+      "reasonNotChosen": "Optimises the rare case (a human tailing) against the common case (machine aggregation); correlation and field extraction become regex archaeology."
+    },
+    {
+      "name": "Wide-event single emission",
+      "summary": "One large structured event per request instead of line-per-happening.",
+      "reasonNotChosen": "Excellent for request analytics but loses intra-request ordering and mid-request visibility on long or crashed requests; the completion line in this decision captures most of the benefit without the loss."
+    }
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

package/blueprints/application-api-rest/contributions/adrs/adr-305-application-api-rest-pagination.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-305-application-api-rest-pagination",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Cursor-based pagination as the collection traversal default",
+  "context": "Every collection needs a pagination story, and the story must be the same everywhere or clients write one traversal routine per collection. The realistic candidates are offset/limit and cursor-based.",
+  "decision": "Collections paginate with opaque cursors (?cursor=...&limit=...) returning the shared envelope (items, next, prev, optional total on explicit request). The maximum and default limits are declared per collection with project-wide defaults. Cursors encode position server-side and are write-stable per AC-2109-4. Offset pagination is not offered alongside; a collection with a genuine offset need (random page access in a UI grid) records its own decision superseding this default for that collection alone (application-api-rest-REQ-007).",
+  "consequences": "Deep traversal stays O(page) rather than O(offset), concurrent writes cannot skip or duplicate stable items, and the envelope is one schema in the generated spec. The costs: no random page jumps, cursors must be treated as opaque by clients, and total counts are an explicit opt-in because counting is the expensive operation cursor pagination exists to avoid.",
+  "alternativesConsidered": [
+    {
+      "name": "Offset/limit pagination",
+      "summary": "?offset=200&limit=50 with page numbers derivable client-side.",
+      "reasonNotChosen": "Degrades linearly with depth on most stores, and concurrent inserts and deletes shift the window, silently skipping or duplicating rows mid-traversal."
+    },
+    {
+      "name": "Both offered per collection",
+      "summary": "Let each collection choose or offer both parameter sets.",
+      "reasonNotChosen": "Two traversal dialects doubles client logic and test surface, and the choice decays into accident; a single default with a decision-record escape hatch keeps intent visible."
+    }
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

package/blueprints/application-api-rest/contributions/adrs/adr-306-application-api-rest-idempotency.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-306-application-api-rest-idempotency",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Idempotency-Key with a server-side replay cache for duplicate-harmful mutations",
+  "context": "Clients retry; networks guarantee it. For mutations whose double application harms (creations, payments, state transitions), the service needs a mechanism that makes a retry safe without asking every client to build its own de-duplication.",
+  "decision": "Duplicate-harmful operations declare Idempotency-Key required in the contract. The server keys a replay cache on (endpoint, principal, key): first execution stores the response, repeats within the declared TTL (default 24 hours, project-configurable) replay it, same key with a different body is 422, concurrent duplicate is 409 while the original is in flight. The cache lives in the project's shared state store so replay works across instances (application-api-rest-REQ-010, application-api-rest-US-2112).",
+  "consequences": "Retries become free for clients and safe for the business. The costs: a state-store dependency for the cache, TTL-bounded storage per keyed mutation, and the declared-required set must be maintained as the surface grows; the contract validation that already checks auth classes checks the idempotency declaration the same way.",
+  "alternativesConsidered": [
+    {
+      "name": "Natural-key idempotency only",
+      "summary": "Rely on unique constraints (one order per cart, one user per email) to reject duplicates.",
+      "reasonNotChosen": "Covers creations with natural keys and nothing else; state transitions and value-carrying operations have no natural key, and the client gets a constraint error rather than the original response."
+    },
+    {
+      "name": "Client-side de-duplication",
+      "summary": "Require clients not to retry non-safe verbs without their own tracking.",
+      "reasonNotChosen": "Pushes the hardest distributed-systems problem onto every client, and one badly behaved client still produces duplicates the business pays for."
+    }
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

package/blueprints/application-api-rest/contributions/adrs/adr-307-application-api-rest-openapi-generation.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-307-application-api-rest-openapi-generation",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "OpenAPI generated from source at build time, defended by drift validation",
+  "context": "The contract document can be authored spec-first (hand-written spec, implementation follows) or generated from the implementation. Either can work; what cannot work is a hand-maintained spec beside a moving implementation with nothing enforcing agreement.",
+  "decision": "The OpenAPI 3.1 document is generated from route definitions and schema annotations at build time (TAC-303). The same endpoint metadata drives enforcement (auth classes, rate overrides, idempotency requirements), so declaration and behaviour share one source. Drift validation runs in the build on three axes: implemented-but-undeclared, declared-but-unimplemented, and type-level response mismatch; any of the three fails the build (application-api-rest-REQ-004, application-api-rest-US-2105).",
+  "consequences": "The served spec is always the running service's spec, and documentation freshness stops being a human virtue. The cost is that contract review happens through code review of routes and schemas rather than of a standalone spec file; the generated artefact should be diffed in review to keep contract changes visible, and the drift validator is the backstop when someone forgets.",
+  "alternativesConsidered": [
+    {
+      "name": "Spec-first authoring",
+      "summary": "Hand-write the OpenAPI document; generate or validate the implementation from it.",
+      "reasonNotChosen": "Strong for API-design-led teams but requires tooling to force the implementation into agreement anyway; with an agent implementing from acceptance criteria, the criteria are the design authority and the spec is better derived than duplicated."
+    },
+    {
+      "name": "Hand-written spec, no enforcement",
+      "summary": "Maintain the spec beside the code by discipline.",
+      "reasonNotChosen": "Drifts the first sprint someone is busy; this is the failure mode the requirement exists to eliminate."
+    }
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}