test: Backend response contract tests against OpenAPI spec

[joelpeace48-cell]

Background & current state

Backend responses can drift from backend/openapi.yaml. There are integration tests, but no automated check that live responses conform to the documented schema.

Goal

Add contract tests validating live API responses against the OpenAPI schema in CI, failing on mismatch.

Technical design

• For each endpoint, validate responses against the OpenAPI schema (e.g., ajv + the spec, or jest-openapi/supertest). Run in CI across representative requests (success + error shapes).
• Pairs with codegen drift check (NEW-088).

Edge cases

• Error responses must also match documented schemas.
• Optional/nullable fields.
• Spec gaps → fix spec or response.

Task breakdown

• Response-vs-schema validation harness over endpoints.
• CI job; cover success + error shapes.
• Fix discovered mismatches.

Acceptance criteria

• A response/schema mismatch fails CI.

Testing & verification

• CI contract-test job; introduce a deliberate mismatch → red.

Out of scope

• Client codegen (NEW-088).

Dependencies / related

• Uses openapi.yaml; complements NEW-088.

Difficulty: easy–medium · Effort: S–M · ci