[High] Generate TypeScript types and runtime validators from the relay's OpenAPI spec with contract-drift checks

[james2177]

Category: Testing, Design System & Community Tooling

Description: Types in src/lib/types.ts and validators in src/lib/schemas.ts are hand-maintained mirrors of the backend. Generate them from the vortex-backend OpenAPI (or JSON Schema) document, commit the spec snapshot, and add CI drift detection.

Problem Statement & Context: Silent API drift is the most likely source of production frontend bugs in a multi-repo system. A generated, versioned contract turns drift into a compile-time and CI-time signal.

Scope & Acceptance Criteria:

• spec/relay.openapi.json snapshot (with source commit/version in a header comment or sidecar file) and a generation script (npm run gen:api) producing typed models and validators into src/lib/generated/ (generated files are marked, formatted, and excluded from coverage/lint as appropriate).
• Hand-written types are replaced by re-exports/aliases of generated ones where compatible; differences are documented (e.g. FE-specific derived types).
• CI job contract-drift: fetches the latest spec from the backend repo/release (configurable URL) and fails (or opens an issue) when it differs from the snapshot or when generation output changes; PR template includes a "spec updated" checkbox.
• Backward-compat rules: unknown enum values map to "unknown" fallbacks at the boundary instead of crashing.
• Out of scope: modifying the backend.

Implementation Guidelines (Suggested Execution):

1. Key Files/Modules: new spec/, new scripts/gen-api.mjs, src/lib/{types,schemas,api}.ts, .github/workflows/, .github/PULL_REQUEST_TEMPLATE.md.
2. Design/Architecture: Prefer a small, dependency-light generator (or a vetted tool passing the dependency policy); generated validators integrate with the response-schema layer.
3. Edge Cases/Constraints: spec not yet available (start with a hand-authored spec derived from current types and docs/websocket-protocol.md), numeric-string amounts, nullable vs optional under exactOptionalPropertyTypes.
4. Testing: Golden tests for the generator on a small spec; drift-check script tests; ≥ 90% coverage of custom generator logic.

Definition of "Done": Baseline DoD, plus documented update procedure "The backend changed — now what?".

Resources: OpenAPI 3.1 spec, docs/websocket-protocol.md.

Complexity: High (200 points)

Baseline Definition of Done (applies to every Wave issue)

Each issue's own "Definition of Done" is in addition to this baseline:

• Code, tests and documentation are included in one PR that references the issue.
• npm run lint, npm run typecheck, npm test, npm run check:i18n and npm run check:editorconfig pass locally and in CI. (If a command is broken by pre-existing repo debris, see the Repository Health & Build Integrity issues — do not silence the check; note the blocker in the PR.)
• No new any, no // @ts-ignore / eslint-disable without a justification comment, and no new console.* (use secureLogger from src/lib/secureLogging.ts).
• All new user-facing strings go through the i18n catalog (src/lib/i18n/messages/en.ts and es.ts).
• New interactive UI is keyboard-operable, has visible focus, correct ARIA semantics, and works in both the dark and light palettes defined in src/app/globals.css.
• UI changes include before/after screenshots (desktop and ~400px mobile). Behaviour changes include a short screen recording or test output.
• Relevant docs under docs/ (and README.md if routes/scripts/env vars change) are updated.
• The PR is reviewed and approved by a maintainer listed in .github/CODEOWNERS.