[Relay][P1] Generar contratos tipados/versionados y OpenAPI

[0bkevin]

Contexto auditado

T3 Connect define endpoints, payloads, errores y auth en un contrato compartido, genera el servidor/cliente HTTP, publica /openapi.json y docs, y comparte los mismos schemas entre relay y clientes. Referencias: relay contracts, Api.ts y worker.ts.

Brecha actual

Brio tiene JSON Schema para el frame, pero CI solo valida que el JSON sea sintácticamente correcto. RelayFrame en Mobile, Frame en Go connector y tunnelFrame en Relay están duplicados y no se generan ni validan como un contrato discriminado común. REST también usa bodies ad hoc. No hay versión de protocolo, negociación de capabilities, OpenAPI ni catálogo exhaustivo de errores/retryability.

Propuesta

1. Definir un contrato canónico versionado para REST y tunnel frames.
2. Modelar cada frame como unión discriminada con campos requeridos/prohibidos, límites y semántica terminal.
3. Generar tipos/validadores para Go y TypeScript; validar en cada frontera antes de rutear.
4. Añadir handshake con protocol version, server/client capabilities y límites efectivos.
5. Estructurar errores con code, message segura, retryable, retry_after, request_id/trace_id y detalles permitidos.
6. Generar OpenAPI/docs para REST y una especificación equivalente para WebSocket.
7. Mantener una política de compatibilidad N/N-1 y feature gating, con migración explícita para cambios breaking.
8. Añadir CI de drift: regeneración limpia, fixtures compartidos y pruebas cruzadas Mobile ↔ Relay ↔ connector.

Criterios de aceptación

• No existen definiciones manuales divergentes del mismo frame.
• Un campo requerido nuevo produce un error de compatibilidad legible en CI.
• Cliente antiguo recibe capabilities compatibles o un upgrade_required accionable, nunca un fallo ambiguo.
• Frames desconocidos/malformados fallan antes de tocar hub/Hermes.
• OpenAPI refleja auth, límites, status y todos los errores reales.
• Golden fixtures válidos e inválidos pasan por implementaciones Go y TypeScript.
• La versión y capacidades negociadas quedan visibles en diagnostics sin exponer secretos.

Issue de ejecución Relay para el objetivo más amplio de #4.