# 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.