@openmarket/rooms-client 0.1.0

package/src/shared/rooms-protocol.ts

@@ -0,0 +1,1339 @@
+export const RoomClientMessageType = {
+  AUTHENTICATE: "AUTHENTICATE",
+  CREATE_ROOM: "CREATE_ROOM",
+  INVITE: "INVITE",
+  REMOVE_MEMBER: "REMOVE_MEMBER",
+  SEARCH: "SEARCH",
+  JOIN: "JOIN",
+  HISTORY: "HISTORY",
+  PEEK: "PEEK",
+  LEAVE: "LEAVE",
+  POST: "POST",
+  REACT: "REACT",
+  EDIT: "EDIT",
+  DELETE: "DELETE",
+  THREAD: "THREAD",
+  PIN: "PIN",
+  UNPIN: "UNPIN",
+  PINS: "PINS",
+  REACTORS: "REACTORS",
+  REPORT: "REPORT",
+  MUTE: "MUTE",
+  KICK: "KICK",
+  BAN: "BAN",
+  ROLE_CHANGE: "ROLE_CHANGE",
+  SET_READ_ONLY: "SET_READ_ONLY",
+  AUDIT_LOG: "AUDIT_LOG",
+  SPACES: "SPACES",
+  JOIN_SPACE: "JOIN_SPACE",
+  READ_STATE: "READ_STATE",
+  SEARCH_ENTRIES: "SEARCH_ENTRIES",
+  WHO: "WHO",
+  TYPING: "TYPING",
+  STATUS: "STATUS",
+  ACK: "ACK",
+  PING: "PING",
+  FRIENDS: "FRIENDS",
+  DM_OPEN: "DM_OPEN",
+  DM_HISTORY: "DM_HISTORY",
+  DM_SEND: "DM_SEND",
+  DM_READ: "DM_READ",
+  TOPIC_CREATE: "TOPIC_CREATE",
+  TOPIC_RENAME: "TOPIC_RENAME",
+  TOPIC_MOVE: "TOPIC_MOVE",
+  TOPIC_MERGE: "TOPIC_MERGE",
+  TOPIC_RESOLVE: "TOPIC_RESOLVE",
+  TOPIC_SET_ATTENTION: "TOPIC_SET_ATTENTION",
+  TOPIC_LIST: "TOPIC_LIST",
+} as const;
+
+export type RoomClientMessageType =
+  (typeof RoomClientMessageType)[keyof typeof RoomClientMessageType];
+
+export const RoomServerMessageType = {
+  AUTH_SUCCESS: "AUTH_SUCCESS",
+  ROOM_CREATED: "ROOM_CREATED",
+  ROOM_INVITED: "ROOM_INVITED",
+  ROOM_MEMBER_REMOVED: "ROOM_MEMBER_REMOVED",
+  ROOMS: "ROOMS",
+  BACKFILL: "BACKFILL",
+  HISTORY: "HISTORY",
+  PEEK_RESULT: "PEEK_RESULT",
+  MESSAGE: "MESSAGE",
+  ENTRY_UPDATED: "ENTRY_UPDATED",
+  THREAD: "THREAD",
+  PINS: "PINS",
+  REACTORS: "REACTORS",
+  ROOM_REPORTED: "ROOM_REPORTED",
+  ROOM_MUTED: "ROOM_MUTED",
+  ROOM_BANNED: "ROOM_BANNED",
+  ROOM_MEMBER_ROLE_CHANGED: "ROOM_MEMBER_ROLE_CHANGED",
+  ROOM_READ_ONLY_SET: "ROOM_READ_ONLY_SET",
+  ROOM_AUDIT_LOG: "ROOM_AUDIT_LOG",
+  SPACES: "SPACES",
+  SPACE_JOINED: "SPACE_JOINED",
+  SPACE_MEMBER_ADDED: "SPACE_MEMBER_ADDED",
+  SPACE_INVITE: "SPACE_INVITE",
+  ROOM_UPDATED: "ROOM_UPDATED",
+  SPACE_UPDATED: "SPACE_UPDATED",
+  READ_STATE: "READ_STATE",
+  SEARCH_RESULTS: "SEARCH_RESULTS",
+  PRESENCE: "PRESENCE",
+  RESYNC: "RESYNC",
+  PRESENCE_DELTA: "PRESENCE_DELTA",
+  WHO: "WHO",
+  TYPING: "TYPING",
+  ERROR: "ERROR",
+  PONG: "PONG",
+  FRIENDS: "FRIENDS",
+  DM_OPENED: "DM_OPENED",
+  DM_HISTORY: "DM_HISTORY",
+  DM_MESSAGE: "DM_MESSAGE",
+  DM_INBOX_UPDATED: "DM_INBOX_UPDATED",
+  TOPIC: "TOPIC",
+  TOPICS: "TOPICS",
+  TOPIC_UPDATED: "TOPIC_UPDATED",
+} as const;
+
+export function addBounded<T>(set: Set<T>, value: T, max: number): void {
+  set.add(value);
+  while (set.size > max) {
+    const oldest = set.values().next().value as T | undefined;
+    if (oldest === undefined) return;
+    set.delete(oldest);
+  }
+}
+
+export type RoomServerMessageType =
+  (typeof RoomServerMessageType)[keyof typeof RoomServerMessageType];
+
+export const SUPPORTED_ROOM_PROTOCOL_VERSION = 2;
+
+export const RoomLedgerEntryType = {
+  POST: "post",
+  SYSTEM: "system",
+  SYSTEM_MARKET: "system_market",
+  MODERATION: "moderation",
+  SECRET: "secret",
+} as const;
+
+export type RoomLedgerEntryType = (typeof RoomLedgerEntryType)[keyof typeof RoomLedgerEntryType];
+
+/** Sealed-secrets envelope on a `secret` entry. Opaque everywhere except the
+ *  recipients' daemons: armored age ciphertext plus recipient userIds. The
+ *  `kind` reveals only whether a text value or a file reference is inside. */
+export interface RoomLedgerSecretPayload {
+  armored: string;
+  recipients: string[];
+  kind: "text" | "file";
+}
+
+export function isSystemRoomLedgerEntryType(type: RoomLedgerEntryType): boolean {
+  return (
+    type === RoomLedgerEntryType.SYSTEM ||
+    type === RoomLedgerEntryType.SYSTEM_MARKET ||
+    type === RoomLedgerEntryType.MODERATION
+  );
+}
+
+export type RoomMemberTier = "free" | "paid";
+export type RoomUserStatus = "online" | "idle" | "dnd";
+export type RoomAccessMode = "public" | "invite_only" | "code" | "space";
+export type RoomSearchScope = "canonical" | "community" | "all";
+export type RoomRole = "owner" | "admin" | "mod" | "member";
+/** Per-channel topics dial, owner-set data. Defaults to "allowed" since the
+ *  2026-07-12 dial-default flip (see RoomMeta.topicsPolicy for the wire
+ *  semantics of an absent value). */
+export type RoomTopicsPolicy = "off" | "allowed" | "required";
+export type RoomTopicAttention = "follow" | "default" | "mute";
+
+export interface RoomMember {
+  userId: string;
+  username: string;
+  handle: string;
+  isAgent: boolean;
+  roomRole?: RoomRole | null | undefined;
+  chatRole?: string | null | undefined;
+  status?: RoomUserStatus | undefined;
+  tier?: RoomMemberTier | null | undefined;
+  since?: string | number | null | undefined;
+  joinedAt: number;
+  avatarUrl?: string | null;
+  statusText?: string | null;
+}
+
+export interface RoomMeta {
+  name: string;
+  title: string;
+  description: string;
+  kind: string;
+  symbols: string[];
+  community?: boolean | undefined;
+  access?: RoomAccessMode | undefined;
+  maxMembers?: number | undefined;
+  createdByUserId?: string | undefined;
+  createdByHandle?: string | undefined;
+  category?: string | null | undefined;
+  sortOrder?: number | undefined;
+  spaceId?: string | null | undefined;
+  postingRoles?: RoomRole[] | undefined;
+  postingRolesRestricted?: boolean | undefined;
+  viewerRole?: RoomRole | null | undefined;
+  /** Head event sequence; diff against the read cursor for unread badges. */
+  headSeq?: number | undefined;
+  /** Topics dial for this channel. Absent reads as "allowed" since the
+   *  2026-07-12 dial-default flip (post-flip relays always advertise the
+   *  stored value, "off" included); explicit "off" means topics are inert. */
+  topicsPolicy?: RoomTopicsPolicy | undefined;
+  tags?: string[] | undefined;
+  entities?: string[] | undefined;
+  sourceRefs?: Array<Record<string, unknown>> | undefined;
+  readOnly?: boolean | undefined;
+  heat?:
+    | {
+        score?: number | undefined;
+        roomHeat?: number | undefined;
+        marketHeat?: number | undefined;
+        heatKind?: "room" | "market" | "mixed" | undefined;
+        messageRate?: number | undefined;
+        freshMessageRate?: number | undefined;
+        recentMessageCount?: number | undefined;
+        baselineMessageRate?: number | undefined;
+        surge?: number | undefined;
+        onlineCount?: number | undefined;
+        activeSenders?: number | undefined;
+        updatedAt?: string | number | undefined;
+      }
+    | null
+    | undefined;
+  onlineCount?: number | undefined;
+}
+
+export interface RoomLedgerEntry {
+  seq: number;
+  ts: number;
+  room: string;
+  handle: string;
+  userId: string;
+  isAgent: boolean;
+  type: RoomLedgerEntryType;
+  text?: string | undefined;
+  secret?: RoomLedgerSecretPayload | undefined;
+  clientMsgId?: string | undefined;
+  receiptId?: string | undefined;
+  inReplyTo?: number | undefined;
+  /** Registry-backed topic this entry was posted into; absent = untopicked. */
+  topicId?: string | undefined;
+  tier?: RoomMemberTier | null | undefined;
+  since?: string | number | null | undefined;
+  reactions?: Array<{ emoji: string; count: number }> | undefined;
+  editedAt?: string | number | Date | undefined;
+  deletedAt?: string | number | Date | undefined;
+  deletedBy?: string | undefined;
+  replyCount?: number | undefined;
+  lastReplyAt?: string | number | Date | undefined;
+  pinned?: boolean | undefined;
+  pinnedBy?: string | null | undefined;
+  pinnedAt?: string | number | Date | null | undefined;
+  attachments?: RoomAttachment[] | undefined;
+  roomRole?: RoomRole | null | undefined;
+}
+
+export interface RoomAttachment {
+  /** Object key under room-attachments/; clients sign it at render time. */
+  key: string;
+  name: string;
+  size: number;
+  mime: string;
+  scanStatus?: "pending" | "clean" | "held" | undefined;
+}
+
+/**
+ * A registry-backed topic inside a channel. The id is permanent: rename
+ * changes `name` only, and links (`om://topic/<topicId>`) keep resolving.
+ * A merged topic stays resolvable via `mergedInto` (its own id never changes
+ * either; readers follow the alias to the surviving topic).
+ */
+export interface RoomTopic {
+  topicId: string;
+  room: string;
+  name: string;
+  resolved: boolean;
+  createdByUserId?: string | undefined;
+  mergedInto?: string | null | undefined;
+}
+
+export interface RoomAuthSuccessPayload {
+  userId: string;
+  username: string;
+  handle: string;
+  isAgent?: boolean;
+  isGuest?: boolean;
+  connectionId: string;
+  protocolVersion: number;
+  minClientBuild?: string | undefined;
+}
+
+export interface RoomBackfillPayload {
+  room: string;
+  entries: RoomLedgerEntry[];
+  upToSeq: number;
+  hasMore: boolean;
+  readOnly?: boolean | undefined;
+  beforeSeq?: number;
+  sinceSeq?: number;
+  atMs?: number;
+  requestId?: string;
+}
+
+export interface RoomMessagePayload {
+  room: string;
+  seq: number;
+  entry: RoomLedgerEntry;
+  requestId?: string;
+}
+
+export type RoomEntryUpdatedPayload = RoomMessagePayload;
+
+export interface RoomThreadPayload {
+  room: string;
+  rootSeq: number;
+  entries: RoomLedgerEntry[];
+  upToSeq: number;
+  hasMore: boolean;
+  requestId?: string | undefined;
+}
+
+export interface RoomPinsPayload {
+  room: string;
+  pins: RoomLedgerEntry[];
+  hasMore: boolean;
+  requestId?: string | undefined;
+}
+
+export interface RoomReadStatePayload {
+  readState: Record<string, number>;
+  requestId?: string | undefined;
+}
+
+export interface RoomSearchResultsPayload {
+  room: string;
+  query: string;
+  entries: RoomLedgerEntry[];
+  hasMore: boolean;
+  requestId?: string | undefined;
+}
+
+export interface RoomPresencePayload {
+  room: string;
+  humans: number;
+  agents: number;
+  total: number;
+  guestCount?: number | undefined;
+  sample: RoomMember[];
+  members?: RoomMember[] | undefined;
+  requestId?: string | undefined;
+}
+
+export interface RoomPresenceDeltaPayload {
+  room: string;
+  joined?: RoomMember | undefined;
+  left?: string | undefined;
+  /** In-place identity refresh (status/statusText/avatar changes). */
+  updated?: RoomMember | undefined;
+  humans: number;
+  agents: number;
+  guestCount?: number | undefined;
+}
+
+export const ROOM_PRESENCE_SAMPLE_LIMIT = 50;
+
+/**
+ * Relay typing contract (kiyotaka `room.constants.ts`). Two facts every
+ * client-side typing feature must design against:
+ *
+ * - A typer's roster entry expires ROOM_TYPING_RELAY_ENTRY_TTL_MS after
+ *   their last start frame, and the expiry is pruned lazily on the next
+ *   roster read; it is NEVER broadcast. A client that wants the entry to
+ *   survive a long message must re-send start inside this window, and a
+ *   client rendering the roster must self-expire it locally.
+ * - Roster broadcasts are throttled to one per room per
+ *   ROOM_TYPING_RELAY_BROADCAST_THROTTLE_MS (a trailing broadcast covers
+ *   frames coalesced inside the window), so any roster a client displays
+ *   can be that stale before the next one arrives.
+ */
+export const ROOM_TYPING_RELAY_ENTRY_TTL_MS = 5_000;
+export const ROOM_TYPING_RELAY_BROADCAST_THROTTLE_MS = 2_000;
+
+export function applyRoomPresenceDelta(
+  current: RoomPresencePayload | null | undefined,
+  delta: RoomPresenceDeltaPayload,
+): RoomPresencePayload {
+  let sample = [...(current?.sample ?? current?.members ?? [])];
+  if (delta.left) {
+    const left = delta.left.toLowerCase();
+    sample = sample.filter((member) => member.userId.toLowerCase() !== left);
+  }
+  if (delta.joined) {
+    const joined = delta.joined.userId.toLowerCase();
+    sample = sample.filter((member) => member.userId.toLowerCase() !== joined);
+    if (sample.length < ROOM_PRESENCE_SAMPLE_LIMIT) sample.push(delta.joined);
+  }
+  if (delta.updated) {
+    const updated = delta.updated.userId.toLowerCase();
+    // In-place identity refresh: replace only if already sampled (an update
+    // must not grow the sample past what joins admitted).
+    sample = sample.map((member) =>
+      member.userId.toLowerCase() === updated ? { ...member, ...delta.updated } : member,
+    );
+  }
+  return {
+    ...(current ?? {}),
+    room: delta.room,
+    humans: delta.humans,
+    agents: delta.agents,
+    total: delta.humans + delta.agents,
+    ...(delta.guestCount !== undefined ? { guestCount: delta.guestCount } : {}),
+    sample,
+    members: sample,
+  };
+}
+
+export interface RoomWhoPayload {
+  room: string;
+  members: RoomMember[];
+  offset: number;
+  limit: number;
+  total: number;
+  humans?: number | undefined;
+  agents?: number | undefined;
+  guestCount?: number | undefined;
+  requestId?: string | undefined;
+}
+
+export interface RoomTypingPayload {
+  room: string;
+  users: string[];
+  count: number;
+}
+
+export interface RoomResyncPayload {
+  room: string;
+  reason: "stream_gap" | "stream_poison" | "stale_cursor";
+  sinceSeq?: number | undefined;
+  missing?: number | undefined;
+  attempts?: number | undefined;
+}
+
+export interface RoomErrorPayload {
+  code: string;
+  message: string;
+  details?: unknown;
+  requestId?: string;
+}
+
+export interface RoomFriendPresence {
+  friendshipId?: string | undefined;
+  userId: string;
+  username: string;
+  acceptedAt?: number | undefined;
+  lastMessageAt?: number | undefined;
+}
+
+export interface RoomSearchPayload {
+  requestId?: string;
+  query?: string;
+  scope?: RoomSearchScope;
+  category?: string | string[];
+  tag?: string | string[];
+  kind?: string | string[];
+  entity?: string | string[];
+  symbol?: string | string[];
+  spaceId?: string | string[];
+  hot?: boolean;
+  createdByMe?: boolean;
+  includeArchived?: boolean;
+  limit?: number;
+}
+
+export interface RoomCreatePayload {
+  requestId?: string;
+  name: string;
+  title?: string;
+  description?: string;
+  access?: RoomAccessMode;
+  maxMembers?: number;
+  category?: string;
+  sortOrder?: number;
+  spaceId?: string;
+  postingRoles?: RoomRole[];
+  tags?: string[];
+}
+
+export interface RoomCreatedPayload {
+  requestId?: string;
+  room: RoomMeta;
+  joinCode?: string;
+}
+
+export interface RoomInvitePayload {
+  requestId?: string;
+  room: string;
+  username?: string;
+  userId?: string;
+}
+
+export interface RoomInvitedPayload {
+  requestId?: string;
+  room: string;
+  invitedUserId: string;
+  invitedHandle: string;
+}
+
+export interface RoomRemoveMemberPayload {
+  requestId?: string;
+  room: string;
+  username?: string;
+  userId?: string;
+  reason?: string;
+}
+
+export interface RoomMemberRemovedPayload {
+  requestId?: string;
+  room: string;
+  removedUserId: string;
+  removedHandle: string;
+}
+
+export interface RoomDmParticipant {
+  userId: string;
+  username: string;
+}
+
+export interface RoomDmMessage {
+  id?: string | undefined;
+  _id?: string | undefined;
+  messageId?: string | undefined;
+  conversationId?: string | undefined;
+  senderId?: string | undefined;
+  userId?: string | undefined;
+  senderUsername?: string | undefined;
+  username?: string | undefined;
+  content: string;
+  clientMsgId?: string | undefined;
+  type?: string | undefined;
+  timestamp?: string | number | undefined;
+  createdAt?: string | number | undefined;
+  /** Sealed DM: content is '' and the opaque envelope rides here. */
+  secret?: RoomLedgerSecretPayload | null | undefined;
+  metadata?: Record<string, unknown> | undefined;
+}
+
+export interface RoomDmOpenPayload {
+  requestId?: string;
+  username: string;
+  limit?: number;
+  markRead?: boolean;
+}
+
+export interface RoomDmHistoryPayload {
+  requestId?: string;
+  username?: string;
+  conversationId?: string;
+  before?: number;
+  limit?: number;
+  markRead?: boolean;
+}
+
+export interface RoomDmSendPayload {
+  requestId?: string;
+  username?: string;
+  conversationId?: string;
+  content: string;
+  clientMsgId?: string;
+}
+
+export interface RoomDmReadPayload {
+  requestId?: string;
+  username?: string;
+  conversationId?: string;
+  before?: number;
+}
+
+export interface RoomDmOpenedPayload {
+  requestId?: string;
+  conversationId: string;
+  participant: RoomDmParticipant;
+  messages: RoomDmMessage[];
+  hasMore?: boolean;
+  cursor?: number;
+}
+
+export type RoomDmHistoryResultPayload = RoomDmOpenedPayload;
+
+export interface RoomDmMessagePayload {
+  requestId?: string;
+  conversationId: string;
+  participant: RoomDmParticipant;
+  message: RoomDmMessage;
+  clientMsgId?: string;
+}
+
+export interface RoomDmInboxUpdatedPayload {
+  conversationId: string;
+  participant: RoomDmParticipant;
+  unreadCount: number;
+  lastMessage?: RoomDmMessage;
+  updatedAt?: string | number;
+}
+
+export interface RoomReportPayload {
+  requestId?: string;
+  room: string;
+  seq?: number;
+  targetUserId?: string;
+  reason: string;
+}
+
+export interface RoomReportedPayload {
+  requestId?: string;
+  room: string;
+  target: { kind: "event"; seq: number } | { kind: "membership"; userId: string };
+}
+
+export interface RoomModerateMemberPayload {
+  requestId?: string;
+  room: string;
+  username?: string;
+  userId?: string;
+  reason?: string;
+}
+
+export interface RoomMutePayload extends RoomModerateMemberPayload {
+  until: string | number | Date;
+}
+
+export interface RoomMutedPayload {
+  requestId?: string;
+  room: string;
+  mutedUserId: string;
+  mutedHandle: string;
+  until: string | number | Date;
+}
+
+export interface RoomBannedPayload {
+  requestId?: string;
+  room: string;
+  bannedUserId: string;
+  bannedHandle: string;
+}
+
+export interface RoomRoleChangePayload {
+  requestId?: string;
+  room: string;
+  username?: string;
+  userId?: string;
+  role: RoomRole;
+  reason?: string;
+}
+
+export interface RoomMemberRoleChangedPayload {
+  requestId?: string;
+  room: string;
+  targetUserId: string;
+  targetHandle: string;
+  role: RoomRole;
+  actorUserId?: string;
+}
+
+export interface RoomSetReadOnlyPayload {
+  requestId?: string;
+  room: string;
+  postingRoles: RoomRole[];
+  reason?: string;
+}
+
+export interface RoomReadOnlySetPayload {
+  requestId?: string;
+  room: string;
+  postingRoles: RoomRole[];
+}
+
+export interface RoomAuditLogRequestPayload {
+  requestId?: string;
+  room: string;
+  limit?: number;
+}
+
+export interface RoomAuditEntry {
+  roomId: string;
+  actor: string;
+  action: string;
+  target?: Record<string, unknown> | undefined;
+  reason?: string | undefined;
+  at: string | number | Date;
+}
+
+export interface RoomAuditLogPayload {
+  requestId?: string;
+  room: string;
+  entries: RoomAuditEntry[];
+}
+
+export interface RoomSpace {
+  spaceId: string;
+  name: string;
+  ownerUserId: string;
+  createdAt: string | number | Date;
+  joined?: boolean | undefined;
+  iconUrl?: string | null | undefined;
+}
+
+export interface RoomSpacesPayload {
+  requestId?: string;
+  spaces: RoomSpace[];
+}
+
+export interface RoomJoinSpacePayload {
+  requestId?: string;
+  spaceId: string;
+}
+
+export interface SpaceMemberAddedPayload {
+  spaceId: string;
+  spaceName?: string;
+  role: string;
+  addedBy?: string;
+}
+
+export interface RoomReactorsPayload {
+  room: string;
+  seq: number;
+  reactors: Array<{
+    emoji: string;
+    users: Array<{ userId: string; handle: string }>;
+    count: number;
+  }>;
+  requestId?: string;
+}
+
+export interface SpaceInvitePayload {
+  inviteId: string;
+  spaceId: string;
+  spaceName?: string;
+  role: string;
+  invitedBy?: string;
+}
+
+/** Channel settings changed: full meta replace, or an archive tombstone. */
+export interface RoomUpdatedPayload {
+  room: string;
+  meta?: RoomMeta | undefined;
+  archived?: boolean | undefined;
+}
+
+/** Server settings changed (rename / icon / archive). */
+export interface SpaceUpdatedPayload {
+  spaceId: string;
+  name?: string | undefined;
+  iconUrl?: string | null | undefined;
+  archived?: boolean | undefined;
+}
+
+export interface RoomSpaceJoinedPayload {
+  requestId?: string;
+  space: RoomSpace;
+}
+
+export interface RoomTopicCreatePayload {
+  requestId?: string;
+  room: string;
+  name: string;
+}
+
+export interface RoomTopicRenamePayload {
+  requestId?: string;
+  topicId: string;
+  name: string;
+}
+
+export interface RoomTopicMovePayload {
+  requestId?: string;
+  topicId: string;
+  seqs: number[];
+  toTopicId: string;
+}
+
+export interface RoomTopicMergePayload {
+  requestId?: string;
+  topicId: string;
+  intoTopicId: string;
+}
+
+export interface RoomTopicResolvePayload {
+  requestId?: string;
+  topicId: string;
+  /** Defaults to true (mark resolved) when omitted; false reopens it. */
+  resolved?: boolean;
+}
+
+export interface RoomTopicSetAttentionPayload {
+  requestId?: string;
+  topicId: string;
+  attention: RoomTopicAttention;
+}
+
+export interface RoomTopicListPayload {
+  requestId?: string;
+  room: string;
+  includeResolved?: boolean;
+  /** Also return the caller's per-bucket view state and the room head. */
+  withState?: boolean;
+}
+
+/**
+ * Per-bucket view state for the requesting user: one entry per topicId plus
+ * the reserved '' key for the room's untopicked (linear) messages. lastSeq
+ * and unreadCount cover visible user messages only; unreadCount also
+ * excludes the caller's own posts and saturates at a server-side cap. The
+ * per-topic cursors and the room-wide cursor are independent per the phase
+ * 2 contract: a linear read never implies a topic was seen, and vice versa.
+ */
+export interface RoomTopicBucketState {
+  lastSeq: number;
+  unreadCount: number;
+  cursor: number;
+  attention: RoomTopicAttention;
+}
+
+export interface RoomTopicResultPayload {
+  room: string;
+  topic: RoomTopic;
+  requestId?: string | undefined;
+}
+
+export interface RoomTopicsResultPayload {
+  room: string;
+  topics: RoomTopic[];
+  /** Present when the request asked withState: keyed by topicId plus ''. */
+  state?: Record<string, RoomTopicBucketState> | undefined;
+  /** Present when the request asked withState: the room head seq. */
+  headSeq?: number | undefined;
+  requestId?: string | undefined;
+}
+
+/** Broadcast to the room on any topic mutation (create/rename/move/merge/resolve). */
+export interface RoomTopicUpdatedPayload {
+  room: string;
+  topic: RoomTopic;
+}
+
+export type RoomClientMessage =
+  | {
+      type: typeof RoomClientMessageType.AUTHENTICATE;
+      payload: {
+        token?: string;
+        username?: string;
+        handle?: string;
+        isAgent?: boolean;
+        protocolVersion?: number;
+      };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.CREATE_ROOM;
+      payload: RoomCreatePayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.INVITE;
+      payload: RoomInvitePayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.REMOVE_MEMBER;
+      payload: RoomRemoveMemberPayload;
+      timestamp?: number;
+    }
+  | { type: typeof RoomClientMessageType.SEARCH; payload: RoomSearchPayload; timestamp?: number }
+  | {
+      type: typeof RoomClientMessageType.JOIN;
+      payload: {
+        room: string;
+        workspaceId?: string;
+        requestId?: string;
+        code?: string;
+        sinceSeq?: number;
+        limit?: number;
+        reason?: string;
+        source?: string;
+        hook?: string;
+        suggestionId?: string;
+      };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.HISTORY;
+      payload: {
+        room: string;
+        requestId?: string;
+        sinceSeq?: number;
+        beforeSeq?: number;
+        atMs?: number;
+        limit?: number;
+      };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.PEEK;
+      payload: {
+        room: string;
+        requestId?: string;
+        sinceSeq?: number;
+        beforeSeq?: number;
+        atMs?: number;
+        limit?: number;
+      };
+      timestamp?: number;
+    }
+  | { type: typeof RoomClientMessageType.LEAVE; payload: { room: string }; timestamp?: number }
+  | {
+      type: typeof RoomClientMessageType.POST;
+      payload: {
+        room: string;
+        text?: string;
+        attachments?: RoomAttachment[];
+        inReplyTo?: number;
+        /** Post directly into a topic; the room's linear stream is unaffected. */
+        topicId?: string;
+        clientMsgId?: string;
+        reason?: string;
+        requestId?: string;
+      };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.REACT;
+      payload: {
+        requestId?: string;
+        room: string;
+        seq: number;
+        emoji: string;
+        op: "add" | "remove";
+      };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.EDIT;
+      payload: {
+        requestId?: string;
+        room: string;
+        seq: number;
+        text: string;
+      };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.DELETE;
+      payload: {
+        requestId?: string;
+        room: string;
+        seq: number;
+      };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.THREAD;
+      payload: {
+        requestId?: string;
+        room: string;
+        rootSeq: number;
+        beforeSeq?: number;
+        sinceSeq?: number;
+        limit?: number;
+      };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.PIN;
+      payload: { requestId?: string; room: string; seq: number };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.UNPIN;
+      payload: { requestId?: string; room: string; seq: number };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.PINS;
+      payload: { requestId?: string; room: string; limit?: number };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.REACTORS;
+      payload: { requestId?: string; room: string; seq: number; emoji?: string; limit?: number };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.REPORT;
+      payload: RoomReportPayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.MUTE;
+      payload: RoomMutePayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.KICK;
+      payload: RoomModerateMemberPayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.BAN;
+      payload: RoomModerateMemberPayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.ROLE_CHANGE;
+      payload: RoomRoleChangePayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.SET_READ_ONLY;
+      payload: RoomSetReadOnlyPayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.AUDIT_LOG;
+      payload: RoomAuditLogRequestPayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.SPACES;
+      payload?: { requestId?: string };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.JOIN_SPACE;
+      payload: RoomJoinSpacePayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.READ_STATE;
+      payload: { requestId?: string; rooms?: string[] };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.SEARCH_ENTRIES;
+      payload: {
+        requestId?: string;
+        room: string;
+        query: string;
+        beforeSeq?: number;
+        sinceSeq?: number;
+        fromMs?: number;
+        toMs?: number;
+        limit?: number;
+      };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.WHO;
+      payload: { room: string; requestId?: string; offset?: number; limit?: number };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.TYPING;
+      payload: { room: string; state: "start" | "stop" };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.STATUS;
+      payload: { status: RoomUserStatus; statusText?: string | null };
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.ACK;
+      /** `topicId` acks a per-topic cursor; the room-wide cursor is separate. */
+      payload: { room: string; seq: number; topicId?: string };
+      timestamp?: number;
+    }
+  | { type: typeof RoomClientMessageType.PING; payload?: Record<string, never>; timestamp?: number }
+  | {
+      type: typeof RoomClientMessageType.FRIENDS;
+      payload?: Record<string, never>;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.DM_OPEN;
+      payload: RoomDmOpenPayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.DM_HISTORY;
+      payload: RoomDmHistoryPayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.DM_SEND;
+      payload: RoomDmSendPayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.DM_READ;
+      payload: RoomDmReadPayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.TOPIC_CREATE;
+      payload: RoomTopicCreatePayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.TOPIC_RENAME;
+      payload: RoomTopicRenamePayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.TOPIC_MOVE;
+      payload: RoomTopicMovePayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.TOPIC_MERGE;
+      payload: RoomTopicMergePayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.TOPIC_RESOLVE;
+      payload: RoomTopicResolvePayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.TOPIC_SET_ATTENTION;
+      payload: RoomTopicSetAttentionPayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomClientMessageType.TOPIC_LIST;
+      payload: RoomTopicListPayload;
+      timestamp?: number;
+    };
+
+export type RoomServerMessage =
+  | {
+      type: typeof RoomServerMessageType.AUTH_SUCCESS;
+      payload: RoomAuthSuccessPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.ROOM_CREATED;
+      payload: RoomCreatedPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.ROOM_INVITED;
+      payload: RoomInvitedPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.ROOM_MEMBER_REMOVED;
+      payload: RoomMemberRemovedPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.ROOMS;
+      payload: { rooms: RoomMeta[]; requestId?: string };
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.BACKFILL;
+      payload: RoomBackfillPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.HISTORY;
+      payload: RoomBackfillPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.PEEK_RESULT;
+      payload: RoomBackfillPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.MESSAGE;
+      payload: RoomMessagePayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.ENTRY_UPDATED;
+      payload: RoomEntryUpdatedPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.THREAD;
+      payload: RoomThreadPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.PINS;
+      payload: RoomPinsPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.ROOM_REPORTED;
+      payload: RoomReportedPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.ROOM_MUTED;
+      payload: RoomMutedPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.ROOM_BANNED;
+      payload: RoomBannedPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.ROOM_MEMBER_ROLE_CHANGED;
+      payload: RoomMemberRoleChangedPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.ROOM_READ_ONLY_SET;
+      payload: RoomReadOnlySetPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.ROOM_AUDIT_LOG;
+      payload: RoomAuditLogPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.SPACES;
+      payload: RoomSpacesPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.SPACE_JOINED;
+      payload: RoomSpaceJoinedPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.SPACE_MEMBER_ADDED;
+      payload: SpaceMemberAddedPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.ROOM_UPDATED;
+      payload: RoomUpdatedPayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.SPACE_UPDATED;
+      payload: SpaceUpdatedPayload;
+      timestamp?: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.SPACE_INVITE;
+      payload: SpaceInvitePayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.REACTORS;
+      payload: RoomReactorsPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.READ_STATE;
+      payload: RoomReadStatePayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.SEARCH_RESULTS;
+      payload: RoomSearchResultsPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.PRESENCE;
+      payload: RoomPresencePayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.RESYNC;
+      payload: RoomResyncPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.PRESENCE_DELTA;
+      payload: RoomPresenceDeltaPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.WHO;
+      payload: RoomWhoPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.TYPING;
+      payload: RoomTypingPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.ERROR;
+      payload: RoomErrorPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.PONG;
+      payload: Record<string, never>;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.FRIENDS;
+      payload: { friends: RoomFriendPresence[] };
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.DM_OPENED;
+      payload: RoomDmOpenedPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.DM_HISTORY;
+      payload: RoomDmHistoryResultPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.DM_MESSAGE;
+      payload: RoomDmMessagePayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.DM_INBOX_UPDATED;
+      payload: RoomDmInboxUpdatedPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.TOPIC;
+      payload: RoomTopicResultPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.TOPICS;
+      payload: RoomTopicsResultPayload;
+      timestamp: number;
+    }
+  | {
+      type: typeof RoomServerMessageType.TOPIC_UPDATED;
+      payload: RoomTopicUpdatedPayload;
+      timestamp: number;
+    };
+
+export type RoomServerMessageOf<T extends RoomServerMessageType> = Extract<
+  RoomServerMessage,
+  { type: T }
+>;