Initial Commit

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

@@ -0,0 +1,63 @@
+# 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.