[High] AsyncAPI Specification and Versioned WebSocket Protocol

[james2177]

Description:
Formally specify the WS protocol (messages, subscriptions, replay, errors) in AsyncAPI, validate all inbound/outbound messages against it at runtime in non-production, and add protocol version negotiation.

Problem Statement & Context:
The WS protocol has grown (subscriptions, filters, replay) but lives only in code. Integrators reverse-engineer it and any change risks silent breakage.

Scope & Acceptance Criteria:

• docs/asyncapi.yaml covering all message types; served at /docs/ws.
• Sec-WebSocket-Protocol: vortex.v1 negotiation; unknown versions rejected with close code 1002.
• Runtime schema validation (dev/test) and CI check that emitted messages conform.
• Types generated for the SDK from the spec.
• Out of scope: breaking protocol changes.

Implementation Guidelines:

1. Key Files/Modules: src/intents/intents.gateway.ts, new docs/asyncapi.yaml, scripts/generate-client.ts.
2. Design/Architecture: Spec as source of truth; zod/ajv validators generated or hand-mirrored with CI parity test.
3. Edge Cases/Constraints: Clients without subprotocol default to v1 for compatibility.
4. Testing: Contract test asserting every message in test/ws-gateway.e2e-spec.ts validates.

Definition of "Done": Common DoD.

Resources:

• Design reference: N/A (backend-only)
• https://www.asyncapi.com/docs/reference/specification/v3.0.0

---

Common Definition of "Done" (applies in addition to the criteria above):

• Code written, tested, and documented (TSDoc on public APIs, README/runbook/ADR updates where behaviour changes).
• All acceptance criteria met; npm run lint, npm run typecheck, npm test, npm run test:e2e pass in CI.
• PR follows .github/PULL_REQUEST_TEMPLATE, uses a Conventional Commit title (enforced by commitlint), includes test output / metrics screenshots, and references the issue.
• New env vars are added to .env.example variants and src/config/env.validation.ts (the check:env-drift script must pass).
• Reviewed and approved by at least one CODEOWNER.

[tesleem-28]

@tesleem-28 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hi, I reviewed the issue and surrounding code and identified a suitable implementation path. I can take care of the changes and verify that the existing functionality remains intact.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @tesleem-28 to this issue.

[aliyuHabibu]

@aliyuHabibu has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hi maintainer please assign this issue to me. Thank you

ℹ️ Repo Maintainers: To accept this application, review their application or assign @aliyuHabibu to this issue.

[Demilade10]

@Demilade10 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hi I can fix this

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Demilade10 to this issue.

[drips-wave]

Congratulations, @Demilade10! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on September 30, 2026.

🧑‍💻 @Demilade10: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊