---
kind: task
slug: chat-realtime-delivery
title: Deliver scalable realtime chat events
plan_slug: workspace-communications
epic_slug: workspace-chat
status: ready
priority: P1
tenant_id: global
owner: unassigned
cursor_todo_id: null
updated_at: "2026-10-22"
---

# Task summary

Broadcast committed chat events over authenticated WebSockets and support horizontal fan-out and reconnect recovery.

## Description

Use HTTP/tRPC for commands and Postgres as the source of truth. Consume the outbox contract and atomic writes established by the persistence task; do not create a second message transaction. A worker claims and publishes normalized events through Redis to authenticated WebSocket subscribers. Each channel uses its own `(channel_id, sequence)` cursor, and clients reconnect by replaying missed rows from Postgres per authorized channel. Reuse Hocuspocus/Yjs only for presence, typing, or drafts rather than canonical history.

## Subtasks

- [ ] Finalize one versioned envelope for message, reply, tombstone, channel lifecycle, membership, and read-state events using the existing outbox contract.
- [ ] Add subscriptions/replay using workspace AND context AND channel access; recheck at delivery, close revoked subscriptions, and test that removed access never receives subsequent payloads. No same-workspace-only shortcut or unsupported-object fallback.
- [ ] Claim and publish outbox events through Redis with retry and idempotent consumption semantics.
- [ ] Add per-channel reconnect catch-up and cross-device read-state invalidation.
- [ ] Add heartbeat, backpressure, graceful-shutdown, outage, ordering, and authorization tests.

## Owner or assignee

`unassigned`

## Status

`ready`

## Estimation

`L`

## Acceptance criteria

- [ ] A message is visible through the query API even when Redis is unavailable.
- [ ] Multiple realtime instances deliver committed events to local subscribers.
- [ ] Clients recover each subscribed channel from its own sequence without duplicates or assumed cross-channel ordering.
- [ ] Subscription authorization matches public/private/direct/archived rules and is rechecked against current workspace/channel access.
- [ ] Durable mark-read events reconcile unread badges on another connected device.
- [ ] `pnpm lint && pnpm type-check && pnpm test` pass; `pnpm build` passes for changed server entry points.

## Links to related Epic / Plan

- Epic: `./Epic-workspace-chat.md`
- Plan: `../Plan-workspace-communications.md`