Add validation rule: x-correlator documentation coverage (request parameter + response header)

[hdamker]

Problem description

The CAMARA API Design Guide requires the x-correlator header to be documented in the OpenAPI
definition — §5.8.5 "x-correlator Header" marks it Required in OAS Definition: Yes, and the
§5.7.6 response template places x-correlator on the headers of the 2xx response. In
practice this is:

1. every operation documents an x-correlator request header parameter;
2. every documented response — success and error — documents the x-correlator response
   header.

CAMARA Validation does not currently check this. A review of a recent release candidate
(camaraproject/DedicatedNetworks#131) found operations with no x-correlator request
parameter, success responses with no x-correlator response header, and a Generic400
response missing the header while its 401/403/404 siblings had it — none of which raised
a validation finding. An analysis across the published API definitions shows the gap is
widespread (roughly 15% of operations miss the request parameter and ~18% of success responses
miss the header), so this is worth automating.

Possible evolution

Add a Spectral rule (r4 ruleset) — most cleanly as two rules for clear, independent findings:

• camara-x-correlator-request-parameter — every operation documents the x-correlator
  header request parameter.
• camara-x-correlator-response-header — every documented response (success and error)
  documents the x-correlator response header.

Notes for implementation:

• Custom function, not pure declarative. The request check is a presence-of-named-element
  test over the parameters array, and the response check must fire even when a response has
  no headers block at all — so a plain JSONPath given/then will not catch the exact gaps
  seen above. This matches the existing camara-* custom-function rules.
• Resolve $refs, including references to the shared CAMARA_common.yaml — many APIs
  reference Generic4xx there rather than defining the header inline.
• Callbacks in scope. Notification/callback operations document x-correlator at about the
  same rate as regular operations in the current cohort (~91% request param, ~75% response
  header), so the rule should also traverse callbacks.
• Severity: warning. The requirement is an existing Design-Guide MUST, but a large number
  of already-published APIs would produce findings, so it should enter as a warning (which is
  fix-or-document under the meta-release rules) rather than a blocking error, with the option
  to promote to error at a later meta-release once the ecosystem has adapted.

Alternative solution

A single bundled rule with both checks is possible but produces less specific findings; two
rules keep the request-parameter and response-header gaps independently actionable.

Additional context

The canonical sources already comply, so adding this rule does not retroactively break the
reference material:

• CAMARA_common.yaml (current) defines the x-correlator parameter and header components and
  puts the x-correlator header on every Generic4xx/Generic5xx response component.
• The ReleaseTest sample APIs used for regression fully document the parameter and header
  (including callbacks) and would raise no new findings.
• The in-flight error-response restructure in Minimal referenceable error responses + reusable error examples Commonalities#665 (new minimal
  referenceable error responses such as BadRequest400, Unauthenticated401,
  PermissionDenied403, NotFound404) keeps the x-correlator header on every new response
  component, so the rule is compatible with that direction.

The remaining cohort gaps come from APIs carrying a stale copy of the common error responses,
or defining responses inline without the header.