suaveplan/openspec/archive/2026-05-12-websocket-gateway/tasks.md

Tasks — websocket-gateway

Phase 1: Scaffold

• 1.1 Create packages/network/websocket-gateway/, server-tier marker comment.
• 1.2 package.json at 0.1.0, "engines": { "node": ">=20" }, NO browser field.
• 1.3 Test config via createTestConfig(); tests/dep-graph.test.ts.
• 1.4 Add ws (or commit to bun:websocket façade) to root catalog under network-server.

Phase 2: Types + errors

• 2.1 Port types/ → src/types/ + sibling .md.
• 2.2 defineCodes("WS_GATEWAY", [...]): ROOM_NOT_FOUND, ROOM_FULL, CHANNEL_INVALID, AUTH_REJECTED, RATE_LIMITED, INVALID_OPTIONS.
• 2.3 Zod schemas for every public option struct + every wire frame.

Phase 3: Core subsystems

• 3.1 Port room/ — join/leave/broadcast/direct.
• 3.2 Port presence/ — who's in which room.
• 3.3 Port channel/ — channel multiplexing over one WS connection.
• 3.4 Port gateway/ — main WebSocketGateway daemon.

Phase 4: Hooks for unmigrated deps

• 4.1 AuthVerifier callback (JWT integration deferred until @suaveplan/jwt-tenant lands).
• 4.2 AuthorizationCheck callback (RBAC integration deferred).
• 4.3 RateLimitGate callback (rate-limiter integration deferred).
• 4.4 Replace placeholders with real package wiring as each lands on genesis.

Phase 5: Observability + reliability

• 5.1 OTel spans ws_gateway.connect/message/broadcast.
• 5.2 Counters ws_gateway.rooms_active, presence_updates_total.
• 5.3 Histograms ws_gateway.message_dispatch_ms.
• 5.4 Retry + circuit breakers via @suaveplan/retry on outbound integrations.
• 5.5 Idempotency guard via @suaveplan/idempotency on every mutating event.
• 5.6 Webhook delivery via @suaveplan/webhook-client on presence events.
• 5.7 Health / readiness / liveness endpoints (inline until @suaveplan/health-check lands).

Phase 6: Tests + docs

• 6.1 Unit tests via @suaveplan/testing/runner.
• 6.2 fast-check property tests: room invariants, presence eventual consistency, channel mux fairness.
• 6.3 Integration test via @suaveplan/testing-integration: 3-client scenario (rooms + presence + messages), no mocks.
• 6.4 100/100/100/100 coverage gate.
• 6.5 Sibling .md per .ts impl file.
• 6.6 Root README.md with daemon-run + client-pairing examples.

Phase 7: Verification

• 7.1 bunx turbo lint typecheck test --filter=@suaveplan/websocket-gateway green.
• 7.2 bunx turbo test:coverage --filter=@suaveplan/websocket-gateway 100/100/100/100.
• 7.3 bun run docs:check green.
• 7.4 MANIFEST.md regen.
• 7.5 STATUS.md row flipped.

Pre-archive checklist

• Row 1 — Phase 7 green.
• Row 2 — 3-client integration test passes.
• Row 3 — Auth/rate-limit/audit callbacks documented with replacement paths.
• Row 4 — openspec/specs/websocket-gateway/spec.md written.
• Row 5 — Folder archived.