rcf-lite 0.12.0 → 0.13.0

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

@@ -0,0 +1,46 @@
+{
+  "tacId": "TAC-306-application-api-rest-operability",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Operability: probes, lifecycle, migrations, and the meta endpoint",
+  "purpose": "Owns what an orchestrator and an operator need from the outside: the three probe endpoints, the initialisation lifecycle they report on, the forward-only migration machinery, and the /v1/_meta version report.",
+  "responsibilities": [
+    "Serve /healthz/live, /healthz/ready, and /healthz/startup with their specified schemas, exclusions, and documented failure modes (application-api-rest-REQ-006).",
+    "Run the initialisation sequence (config load, migrations, cache warm) and expose its progress to the startup probe (AC-2108-4).",
+    "Register and execute declared readiness checks against downstream dependencies, reporting per-check results in the ready body (AC-2108-2, AC-2108-3).",
+    "Apply migrations strictly forward with named reverts and deterministic ordering (application-api-rest-REQ-014).",
+    "Serve /v1/_meta reporting the live schema version and application version, sourced from the migration record, under a declared auth class (application-api-rest-US-2118)."
+  ],
+  "internalStructure": "A lifecycle coordinator owning initialisation state, a check registry the readiness probe iterates, and the migration runner; probe handlers are thin reads over this state, never performing work themselves.",
+  "interfaces": [
+    {
+      "name": "readiness check registry",
+      "kind": "configuration",
+      "description": "Declared named checks (database, cache, queues) with their timeout budgets; the set the ready probe reports on."
+    },
+    {
+      "name": "probe endpoints",
+      "kind": "http",
+      "description": "The three /healthz/* endpoints and /v1/_meta, with their specced response schemas."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Request pipeline",
+      "kind": "tac",
+      "tacId": "TAC-301-application-api-rest-request-pipeline",
+      "description": "Probes ride the pipeline with declared exemptions from auth, rate limiting, and info-level logging."
+    },
+    {
+      "name": "Observability",
+      "kind": "tac",
+      "tacId": "TAC-305-application-api-rest-observability",
+      "description": "Probe outcomes land in the dedicated probe metric."
+    }
+  ],
+  "tradeoffs": "Probe handlers reading pre-computed state (rather than checking dependencies inline) keeps probes cheap and non-amplifying under orchestrator polling, at the cost of a bounded staleness window in readiness reporting; the check interval is the tuning knob and is declared configuration.",
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,72 @@
+{
+  "usId": "application-api-rest-US-2101",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Noun-based resource surface with scoped hierarchy and declared representations",
+  "asA": "API consumer building a client",
+  "iWant": "every capability expressed as a resource with a predictable URL and one documented representation",
+  "soThat": "I can discover, cache, and integrate against the surface without reading the server source",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2101-1",
+      "description": "Every collection URL is a plural noun; no path segment under the versioned root is a verb or verb phrase.",
+      "given": "the generated OpenAPI path inventory",
+      "when": "path segments are checked against the resource model",
+      "then": "every segment is a plural noun, a resource identifier, or a declared sub-resource; none is a verb",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2101-2",
+      "description": "Nested paths exist only for genuinely 1:N, always-scoped relationships; a resource reachable without its parent is not nested under it.",
+      "given": "the declared resource model and the path inventory",
+      "when": "each nested path is compared against the relationship it models",
+      "then": "every nested path corresponds to a declared 1:N always-scoped relationship and no independent resource is parent-scoped",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2101-3",
+      "description": "Collection filters are expressed as query parameters or declared sub-resources, never as ad-hoc path segments.",
+      "given": "a filtered view of a collection",
+      "when": "the request shape is inspected",
+      "then": "the filter travels as documented query parameters or a declared sub-resource path, not an invented segment",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2101-4",
+      "description": "Every resource class has exactly one documented representation model, and every endpoint returning that class returns that representation.",
+      "given": "two different endpoints returning the same resource class",
+      "when": "their response bodies are compared field by field",
+      "then": "both conform to the same documented representation model",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2101-5",
+      "description": "Standard verb semantics hold: GET is safe and cacheable, PUT and DELETE are idempotent, POST creates or triggers, PATCH partially updates; no endpoint repurposes a verb against its semantics.",
+      "given": "the OpenAPI operation inventory",
+      "when": "each operation's verb and behaviour are reviewed",
+      "then": "every operation's behaviour matches its verb's declared semantics",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2101-6",
+      "description": "Mutating a resource returns the resulting representation (or a Location header on 201) so clients never need a follow-up read to learn the outcome.",
+      "given": "a successful POST, PUT, or PATCH",
+      "when": "the response is inspected",
+      "then": "the body carries the resulting representation, or the 201 response carries a Location header resolving to it",
+      "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-2102.json

@@ -0,0 +1,73 @@
+{
+  "usId": "application-api-rest-US-2102",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "One wire contract: JSON bodies, consistent casing, UTC timestamps, explicit content types",
+  "asA": "API consumer parsing responses mechanically",
+  "iWant": "every body, property name, timestamp, and content type to follow one declared convention",
+  "soThat": "one serialiser configuration handles the entire surface without per-endpoint exceptions",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2102-1",
+      "description": "Every request and response body on the versioned surface is JSON; no endpoint accepts or emits form encoding, XML, or bespoke text formats.",
+      "given": "the full endpoint inventory",
+      "when": "request and response media types are enumerated from the generated spec and observed responses",
+      "then": "every body media type is application/json or a JSON-structured type such as application/problem+json",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2102-2",
+      "description": "Property names follow the project's declared casing (camelCase unless configured otherwise) on every request and response body, with zero mixed-casing endpoints.",
+      "given": "the schemas in the generated OpenAPI spec",
+      "when": "every property name is checked against the declared casing rule",
+      "then": "no property deviates from the declared casing",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2102-3",
+      "description": "Every temporal field is an ISO-8601 timestamp in RFC-3339 form, expressed in UTC with an explicit offset designator.",
+      "given": "any response carrying a temporal field",
+      "when": "the field value is parsed",
+      "then": "it parses as RFC-3339, is in UTC, and carries the offset designator",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2102-4",
+      "description": "Every response, including errors and empty-body statuses, carries an explicit Content-Type header appropriate to its body.",
+      "given": "any endpoint response including 4xx and 5xx paths",
+      "when": "response headers are inspected",
+      "then": "Content-Type is present and correct; no body-bearing response omits it",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2102-5",
+      "description": "A request with an unsupported Content-Type is rejected with 415 and a problem-details body rather than being parsed permissively.",
+      "given": "a POST with a body and a non-JSON Content-Type",
+      "when": "the request is submitted",
+      "then": "the service responds 415 with the declared error envelope",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2102-6",
+      "description": "A request with a syntactically invalid JSON body is rejected with 400 and a problem-details body identifying the parse failure, never a 500.",
+      "given": "a POST with malformed JSON",
+      "when": "the request is submitted",
+      "then": "the service responds 400 with the declared error envelope naming the parse failure",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-301-application-api-rest-request-pipeline",
+    "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-2103.json

@@ -0,0 +1,63 @@
+{
+  "usId": "application-api-rest-US-2103",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Path-versioned contract with announced deprecation and a stated drop policy",
+  "asA": "API consumer maintaining a long-lived integration",
+  "iWant": "the contract version visible in every URL and version retirement announced on the wire",
+  "soThat": "I can plan migrations from response headers instead of discovering breakage in production",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2103-1",
+      "description": "Every business endpoint lives under a major-version path prefix (/v1/...); only the probe endpoints and the documentation endpoints sit outside it.",
+      "given": "the generated OpenAPI path inventory",
+      "when": "paths are checked for the version prefix",
+      "then": "every path is version-prefixed except /healthz/*, /openapi.*, and /docs",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2103-2",
+      "description": "A request to an unrecognised major version returns 404 with a problem-details body naming the supported versions.",
+      "given": "a request to /v9/ where v9 does not exist",
+      "when": "the request is submitted",
+      "then": "the service responds 404 with the declared error envelope listing supported versions",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2103-3",
+      "description": "Breaking changes never land inside an existing major version; additive changes (new fields, new endpoints) are the only in-version evolution.",
+      "given": "two releases of the service within one major version",
+      "when": "their generated specs are diffed",
+      "then": "no field is removed or retyped and no endpoint's contract narrows within the version",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2103-4",
+      "description": "Every response from a deprecated version carries Deprecation and Sunset headers with the retirement date.",
+      "given": "a version marked deprecated",
+      "when": "any of its endpoints responds",
+      "then": "Deprecation and Sunset headers are present and the Sunset date matches the declared policy",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2103-5",
+      "description": "The version-drop policy is stated in the served documentation: minimum notice period and the response clients receive after drop (410 with a problem-details body pointing at the successor version).",
+      "given": "the served documentation and a dropped version",
+      "when": "a request reaches a dropped version",
+      "then": "the service responds 410 with the declared error envelope naming the successor, matching the documented policy",
+      "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-2104.json

@@ -0,0 +1,72 @@
+{
+  "usId": "application-api-rest-US-2104",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "OpenAPI 3.1 generated from source and served alongside interactive documentation",
+  "asA": "API consumer evaluating and integrating the service",
+  "iWant": "a machine-readable spec and browsable documentation generated from the code that is actually running",
+  "soThat": "what I read is what the service does, with no hand-maintained copy to drift",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2104-1",
+      "description": "The OpenAPI 3.1 document is produced from implementation source at build time; the repository contains no hand-written parallel spec that requires separate editing.",
+      "given": "the build pipeline",
+      "when": "the build runs",
+      "then": "the OpenAPI document is emitted as a build artefact derived from source annotations or route definitions, and no hand-maintained duplicate exists",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2104-2",
+      "description": "GET /openapi.json returns the generated spec as application/json and GET /openapi.yaml returns the same spec as YAML; the two are semantically identical.",
+      "given": "a running service",
+      "when": "both documentation URLs are fetched",
+      "then": "both return 200 with correct content types and parse to the same specification",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2104-3",
+      "description": "GET /docs serves interactive documentation rendered from the same generated spec, listing every endpoint with its schemas and auth class.",
+      "given": "a running service",
+      "when": "/docs is loaded",
+      "then": "the documentation UI renders from the served spec and every endpoint in the spec is browsable",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2104-4",
+      "description": "The generated document validates as OpenAPI 3.1: an off-the-shelf validator accepts it with zero errors.",
+      "given": "the generated OpenAPI document",
+      "when": "an OpenAPI 3.1 validator runs against it",
+      "then": "validation passes with zero errors",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2104-5",
+      "description": "Every operation in the generated spec carries an operationId, a summary, request and response schemas, and the x-auth-class extension; no operation ships undocumented.",
+      "given": "the generated OpenAPI document",
+      "when": "each operation is inspected",
+      "then": "operationId, summary, schemas, and x-auth-class are present on every operation",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2104-6",
+      "description": "The documentation endpoints (/openapi.json, /openapi.yaml, /docs) respond according to the project's declared exposure policy, and in non-production environments they are always available.",
+      "given": "the declared exposure policy and a non-production deployment",
+      "when": "the documentation URLs are fetched",
+      "then": "responses match the declared policy, and the non-production deployment serves all three",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "tacIds": [
+    "TAC-303-application-api-rest-contract-surface"
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,63 @@
+{
+  "usId": "application-api-rest-US-2105",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Contract-drift detection: implementation and spec verified against each other",
+  "asA": "platform operator relying on the published contract",
+  "iWant": "any divergence between the implementation and the served spec to fail the build",
+  "soThat": "the spec clients integrate against is provably the service they call",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2105-1",
+      "description": "Every routable endpoint in the implementation has a corresponding entry in the generated spec; an implemented-but-undeclared endpoint fails contract validation.",
+      "given": "the implementation's route table and the generated spec",
+      "when": "the two inventories are compared",
+      "then": "every implemented route appears in the spec, and a deliberately added undeclared route makes the comparison fail",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2105-2",
+      "description": "Every entry in the generated spec has a live implementation; a declared-but-unimplemented operation fails contract validation.",
+      "given": "the generated spec and the running service",
+      "when": "each declared operation is exercised",
+      "then": "none returns a routing-level 404 or 501; a deliberately orphaned spec entry makes validation fail",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2105-3",
+      "description": "Observed response bodies match the spec's response schemas at the type level on every declared status code.",
+      "given": "a representative request per declared operation and status",
+      "when": "each observed response is validated against the spec schema",
+      "then": "every response validates; a type-level mismatch fails the check naming the operation, status, and path into the schema",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2105-4",
+      "description": "Contract validation runs in the build pipeline; drift on any of the three axes breaks the build rather than surfacing after deploy.",
+      "given": "the build pipeline with an injected drift (undeclared endpoint, orphaned entry, or schema mismatch)",
+      "when": "the pipeline runs",
+      "then": "the build fails at the contract-validation step with a message naming the drift",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2105-5",
+      "description": "The contract-validation report enumerates the checked operations so coverage is visible, not inferred.",
+      "given": "a passing contract-validation run",
+      "when": "its report is read",
+      "then": "every declared operation appears with its verification outcome",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-303-application-api-rest-contract-surface"
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,73 @@
+{
+  "usId": "application-api-rest-US-2106",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Auth-class declaration: every endpoint names its class and middleware enforces it",
+  "asA": "security reviewer auditing the API surface",
+  "iWant": "each endpoint's auth posture declared in the contract and enforced by middleware, not by handler code",
+  "soThat": "the auth posture of the whole surface is enumerable from the spec and cannot be silently weakened",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2106-1",
+      "description": "Every operation in the generated OpenAPI spec carries the x-auth-class extension with one of exactly four values: public, user, admin, or service.",
+      "given": "the generated OpenAPI document",
+      "when": "every operation's x-auth-class value is read",
+      "then": "each carries exactly one of the four declared values and no other",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2106-2",
+      "description": "An endpoint without a declared auth class fails contract validation at build time; classlessness is a build failure, not a default.",
+      "given": "a deliberately added endpoint with no auth-class declaration",
+      "when": "contract validation runs",
+      "then": "validation fails naming the classless endpoint",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2106-3",
+      "description": "Class enforcement happens in middleware before the handler runs; a handler is never invoked for a request that fails its endpoint's class check.",
+      "given": "a request failing the endpoint's auth-class check",
+      "when": "the request is processed",
+      "then": "the middleware rejects it and the handler observably does not execute",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2106-4",
+      "description": "Enforcement is driven by the same declaration the spec publishes: changing an endpoint's declared class changes its enforcement with no second edit site.",
+      "given": "an endpoint whose declared class is changed from user to admin",
+      "when": "the service is rebuilt and the endpoint called with a non-admin user token",
+      "then": "the request is rejected per the new class, and the spec and enforcement agree",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2106-5",
+      "description": "Auth rejections use the declared error envelope with correct status semantics: 401 for missing or invalid credentials, 403 for valid credentials lacking the required class.",
+      "given": "requests with absent, invalid, and under-privileged credentials",
+      "when": "each is submitted to a protected endpoint",
+      "then": "responses are 401, 401, and 403 respectively, each with a problem-details body",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2106-6",
+      "description": "The four middleware classes are the only auth paths in the service; no endpoint implements bespoke auth logic outside its class middleware.",
+      "given": "the implementation's auth code paths",
+      "when": "auth logic outside the four class middlewares is searched for",
+      "then": "none exists; every endpoint's auth behaviour is fully attributable to its declared class",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-302-application-api-rest-auth-middleware",
+    "TAC-303-application-api-rest-contract-surface"
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}

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

@@ -0,0 +1,90 @@
+{
+  "usId": "application-api-rest-US-2107",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Per-class behaviour: the four auth classes each honour their declared contract",
+  "asA": "platform operator running the service for multiple caller populations",
+  "iWant": "public, user, admin, and service callers each handled by their class's declared rules",
+  "soThat": "anonymous traffic, users, administrators, and peer services each get exactly the access and accounting they should",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2107-1",
+      "description": "Public endpoints process no auth headers: a request with credentials attached succeeds identically to one without, and no identity is resolved or logged for either.",
+      "given": "a public endpoint",
+      "when": "requests with and without auth headers are submitted",
+      "then": "both succeed with identical behaviour and no resolved identity appears in logs or context",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2107-2",
+      "description": "Public endpoints are rate-limited under the public class limit even for callers who could authenticate.",
+      "given": "a burst of requests to a public endpoint exceeding the public limit",
+      "when": "the burst is submitted",
+      "then": "requests beyond the limit receive 429 per the rate-limiting contract",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2107-3",
+      "description": "User-class endpoints resolve the caller's identity from a session or bearer token and expose it to the handler; requests without a resolvable identity are rejected with 401.",
+      "given": "a user-class endpoint",
+      "when": "requests with a valid token, an expired token, and no token are submitted",
+      "then": "the valid token resolves an identity available to the handler; the other two receive 401 with the error envelope",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2107-4",
+      "description": "Admin-class endpoints require an authenticated identity holding the admin role; an authenticated non-admin receives 403.",
+      "given": "an admin-class endpoint",
+      "when": "an authenticated non-admin and an authenticated admin each call it",
+      "then": "the non-admin receives 403 with the error envelope; the admin succeeds",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2107-5",
+      "description": "Every admin-class request is audit-logged with the acting identity, the endpoint, the outcome, and the request id.",
+      "given": "an admin-class request, successful or rejected",
+      "when": "the audit log is read",
+      "then": "an entry records identity, endpoint, outcome, and request id",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2107-6",
+      "description": "Service-class endpoints authenticate the calling service via mTLS or request signature and resolve no user identity.",
+      "given": "a service-class endpoint",
+      "when": "a correctly signed or mTLS-authenticated peer calls it, and an unauthenticated caller attempts it",
+      "then": "the peer succeeds with a service principal and no user identity; the unauthenticated caller receives 401",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2107-7",
+      "description": "Every service-class request is audit-logged with the calling service principal, and service-class traffic is counted under its own rate limit separate from user traffic.",
+      "given": "service-class traffic at volume alongside user traffic",
+      "when": "audit logs and rate-limit counters are inspected",
+      "then": "service calls are attributed to the service principal and limited under the service-class limit, independent of user-class counters",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2107-8",
+      "description": "A user or admin token presented to a service-class endpoint is rejected: class boundaries do not substitute for each other.",
+      "given": "a valid admin bearer token",
+      "when": "it is presented to a service-class endpoint",
+      "then": "the request is rejected with 403 and the error envelope; the admin token grants nothing outside its classes",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "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-2108.json

@@ -0,0 +1,90 @@
+{
+  "usId": "application-api-rest-US-2108",
+  "prdId": "PRD-001",
+  "reqId": "application-api-rest-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Liveness, readiness, and startup probes that tell the orchestrator the truth",
+  "asA": "platform operator running the service under Kubernetes",
+  "iWant": "three probe endpoints that each answer their one question honestly and cheaply",
+  "soThat": "the orchestrator restarts, routes, and rolls out instances on real signals",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2108-1",
+      "description": "GET /healthz/live returns 200 with the specified response schema whenever the process can serve any request, and performs no dependency checks whatsoever.",
+      "given": "a running instance with a deliberately unreachable database",
+      "when": "/healthz/live is called",
+      "then": "it returns 200 against the specified schema, unaffected by the dependency outage",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2108-2",
+      "description": "GET /healthz/ready returns 200 only when every declared downstream dependency check (database, cache, queues) passes.",
+      "given": "an instance with all declared dependencies reachable",
+      "when": "/healthz/ready is called",
+      "then": "it returns 200 with the specified schema listing each check as passing",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2108-3",
+      "description": "GET /healthz/ready returns 503 with a body enumerating the failed checks by name when any declared dependency is unreachable.",
+      "given": "an instance with one declared dependency down",
+      "when": "/healthz/ready is called",
+      "then": "it returns 503 and the body names the failing check while still listing the passing ones",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2108-4",
+      "description": "GET /healthz/startup returns 200 only after initialisation (migrations applied, cache warmed, config loaded) completes, and a non-200 with the pending steps before that.",
+      "given": "an instance mid-initialisation and the same instance after initialisation",
+      "when": "/healthz/startup is called in each state",
+      "then": "the mid-initialisation call is non-200 naming pending steps; the post-initialisation call is 200",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2108-5",
+      "description": "All three probes sit outside the auth middleware and outside rate limiting: they succeed with no credentials and are never 401, 403, or 429.",
+      "given": "a running instance",
+      "when": "each probe is called with no credentials at sustained frequency",
+      "then": "every call is answered on probe semantics alone, never with an auth or rate-limit status",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2108-6",
+      "description": "Probe requests do not appear in info-level request logs and are excluded from RED endpoint metrics; probe outcomes are recorded under their own dedicated metric.",
+      "given": "a period of steady probe traffic",
+      "when": "info-level logs and endpoint metrics are inspected",
+      "then": "probe requests appear in neither, and the dedicated probe-outcome metric carries their results",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2108-7",
+      "description": "Each probe's response schema and failure mode are documented in the generated spec: what a failure body contains and what an operator should conclude from it.",
+      "given": "the generated OpenAPI document",
+      "when": "the three probe entries are read",
+      "then": "each declares its success and failure schemas and its documented failure mode",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-2108-8",
+      "description": "Readiness reflects recovery: when a failed dependency becomes reachable again, /healthz/ready returns to 200 without a process restart.",
+      "given": "an instance whose dependency outage has been restored",
+      "when": "/healthz/ready is called after restoration",
+      "then": "it returns 200 without the process having restarted",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-306-application-api-rest-operability"
+  ],
+  "createdAt": "2026-08-19T10:00:00Z",
+  "updatedAt": "2026-08-19T10:00:00Z"
+}