@ai-matrx/messaging 0.15.14 → 0.15.16

package/dist/index.cjs

@@ -70,7 +70,8 @@ __export(src_exports, {
   splitText: () => splitText,
   summarizeText: () => summarizeText,
   toMessagingArchiveFilter: () => toMessagingArchiveFilter,
-  unreadCutoff: () => unreadCutoff
+  unreadCutoff: () => unreadCutoff,
+  writeNotApplied: () => writeNotApplied
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -308,6 +309,13 @@ function invalidResponse(operation, detail) {
     "The database returned a shape this package does not accept. Rendering it would put a lie on the screen, so it is refused here. Fix the RPC's return contract."
   );
 }
+function writeNotApplied(operation, detail) {
+  return new MessagingError(
+    "write-not-applied",
+    `${operation}: ${detail}`,
+    "The intended live row was not changed. Re-read it before retrying; the row may be gone, soft-deleted, or hidden from this session by database authorization."
+  );
+}
 
 // src/core/references.ts
 var FENCE = /```matrx\s*\n([\s\S]*?)\n?```/g;
@@ -1087,6 +1095,7 @@ function insertOrdered(messages, message) {
 }
 function createMessagingStore() {
   let conversations = [];
+  let conversationSummaries = /* @__PURE__ */ new Map();
   let hasMoreConversations = false;
   let hasLoadedConversations = false;
   let archiveFilter = DEFAULT_MESSAGING_ARCHIVE_FILTER;
@@ -1095,12 +1104,15 @@ function createMessagingStore() {
   let activeConversationId = null;
   let conversationReadFailures = /* @__PURE__ */ new Map();
   let conversationsLoadError = null;
+  const unreadRevisions = /* @__PURE__ */ new Map();
+  const confirmedReadRevisions = /* @__PURE__ */ new Map();
   const listeners = /* @__PURE__ */ new Set();
   let cached = null;
   function snapshot() {
     if (cached !== null) return cached;
     cached = {
       conversations,
+      conversationSummaries,
       hasMoreConversations,
       hasLoadedConversations,
       threads,
@@ -1119,11 +1131,33 @@ function createMessagingStore() {
     listeners.forEach((listener) => listener(next));
   }
   function normalizeConversations(items) {
-    const active = activeConversationId;
-    const zeroed = active === null ? items : items.map(
-      (item) => item.conversation.id === active && item.unreadCount !== 0 ? { ...item, unreadCount: 0 } : item
+    return [...items].sort((a, b) => a.sortAt < b.sortAt ? 1 : a.sortAt > b.sortAt ? -1 : 0);
+  }
+  function replaceConversations(next) {
+    const summaries = new Map(conversationSummaries);
+    next.forEach((item) => {
+      const id = item.conversation.id;
+      if (summaries.get(id)?.unreadCount !== item.unreadCount) {
+        unreadRevisions.set(id, (unreadRevisions.get(id) ?? 0) + 1);
+      }
+      summaries.set(id, item);
+    });
+    conversationSummaries = summaries;
+    conversations = next;
+  }
+  function replaceOneSummary(id, update) {
+    const held = conversationSummaries.get(id);
+    if (held === void 0) return;
+    const replacement = update(held);
+    if (held.unreadCount !== replacement.unreadCount) {
+      unreadRevisions.set(id, (unreadRevisions.get(id) ?? 0) + 1);
+    }
+    const summaries = new Map(conversationSummaries);
+    summaries.set(id, replacement);
+    conversationSummaries = summaries;
+    conversations = conversations.map(
+      (item) => item.conversation.id === id ? replacement : item
     );
-    return [...zeroed].sort((a, b) => a.sortAt < b.sortAt ? 1 : a.sortAt > b.sortAt ? -1 : 0);
   }
   function threadFor(id) {
     return threads.get(id) ?? {
@@ -1135,7 +1169,9 @@ function createMessagingStore() {
   }
   function writeThread(thread) {
     const next = new Map(threads);
-    const latest = thread.messages.at(-1);
+    const latest = [...thread.messages].reverse().find(
+      (message) => message.deliveryState !== "sending" && message.deliveryState !== "failed" && !message.id.startsWith("optimistic:")
+    );
     next.set(thread.conversationId, {
       ...thread,
       latestAt: latest?.createdAt ?? thread.latestAt
@@ -1151,7 +1187,7 @@ function createMessagingStore() {
       };
     },
     setConversations(items, hasMore) {
-      conversations = normalizeConversations(items);
+      replaceConversations(normalizeConversations(items));
       hasMoreConversations = hasMore;
       hasLoadedConversations = true;
       conversationsLoadError = null;
@@ -1165,7 +1201,7 @@ function createMessagingStore() {
     setArchiveFilter(next) {
       if (next === archiveFilter) return;
       archiveFilter = next;
-      conversations = [];
+      replaceConversations([]);
       hasMoreConversations = false;
       hasLoadedConversations = false;
       emit();
@@ -1177,18 +1213,34 @@ function createMessagingStore() {
     appendConversations(items, hasMore) {
       const byId = new Map(conversations.map((item) => [item.conversation.id, item]));
       items.forEach((item) => byId.set(item.conversation.id, item));
-      conversations = normalizeConversations([...byId.values()]);
+      replaceConversations(normalizeConversations([...byId.values()]));
       hasMoreConversations = hasMore;
       emit();
     },
     upsertConversation(item) {
       const byId = new Map(conversations.map((entry) => [entry.conversation.id, entry]));
       byId.set(item.conversation.id, item);
-      conversations = normalizeConversations([...byId.values()]);
+      replaceConversations(normalizeConversations([...byId.values()]));
+      emit();
+    },
+    setConversationSummary(item) {
+      const id = item.conversation.id;
+      const held = conversationSummaries.get(id);
+      if (held?.unreadCount !== item.unreadCount) {
+        unreadRevisions.set(id, (unreadRevisions.get(id) ?? 0) + 1);
+      }
+      const summaries = new Map(conversationSummaries);
+      summaries.set(id, item);
+      conversationSummaries = summaries;
       emit();
     },
     removeConversation(id) {
-      conversations = conversations.filter((item) => item.conversation.id !== id);
+      replaceConversations(conversations.filter((item) => item.conversation.id !== id));
+      const summaries = new Map(conversationSummaries);
+      summaries.delete(id);
+      conversationSummaries = summaries;
+      unreadRevisions.delete(id);
+      confirmedReadRevisions.delete(id);
       const next = new Map(threads);
       next.delete(id);
       threads = next;
@@ -1196,7 +1248,6 @@ function createMessagingStore() {
     },
     setActiveConversation(id) {
       activeConversationId = id;
-      conversations = normalizeConversations(conversations);
       emit();
     },
     setConversationReadFailure(id, failure) {
@@ -1216,6 +1267,13 @@ function createMessagingStore() {
       });
       emit();
     },
+    clearThread(id) {
+      if (!threads.has(id)) return;
+      const next = new Map(threads);
+      next.delete(id);
+      threads = next;
+      emit();
+    },
     prependOlder(id, messages, hasMoreOlder) {
       const thread = threadFor(id);
       const known = new Set(thread.messages.map((message) => message.id));
@@ -1268,40 +1326,48 @@ function createMessagingStore() {
       emit();
     },
     applyLastMessage(message, args = {}) {
-      const existing = conversations.find(
-        (item) => item.conversation.id === message.conversationId
-      );
+      const existing = conversationSummaries.get(message.conversationId);
       if (existing === void 0) return;
       if (message.deliveryState === "sending" || message.deletedAt !== null) return;
       if (existing.lastMessageAt !== null && message.createdAt < existing.lastMessageAt) return;
-      const isActive = activeConversationId === message.conversationId;
-      const shouldCount = args.incrementUnread === true && !isActive;
-      conversations = normalizeConversations(
-        conversations.map(
-          (item) => item.conversation.id === message.conversationId ? {
-            ...item,
-            lastMessageContent: message.content,
-            lastMessageSenderId: message.senderId,
-            lastMessageAt: message.createdAt,
-            sortAt: message.createdAt,
-            unreadCount: shouldCount ? item.unreadCount + 1 : item.unreadCount
-          } : item
-        )
-      );
+      const shouldCount = args.incrementUnread === true;
+      replaceOneSummary(message.conversationId, (item) => ({
+        ...item,
+        lastMessageContent: message.content,
+        lastMessageSenderId: message.senderId,
+        lastMessageAt: message.createdAt,
+        sortAt: message.createdAt,
+        unreadCount: shouldCount ? item.unreadCount + 1 : item.unreadCount
+      }));
+      conversations = normalizeConversations(conversations);
       emit();
     },
-    markConversationRead(id) {
-      conversations = conversations.map(
-        (item) => item.conversation.id === id ? { ...item, unreadCount: 0 } : item
-      );
+    captureConversationRead(id, at) {
+      const item = conversationSummaries.get(id);
+      return {
+        at,
+        unreadCount: item?.unreadCount ?? 0,
+        revision: unreadRevisions.get(id) ?? 0
+      };
+    },
+    markConversationRead(id, cutoff, canonicalUnreadCount = 0) {
+      if (cutoff.revision <= (confirmedReadRevisions.get(id) ?? -1)) return;
+      confirmedReadRevisions.set(id, cutoff.revision);
+      replaceOneSummary(id, (item) => ({
+        ...item,
+        // The repository re-counts after persisting the exact server cutoff.
+        // If realtime advanced local state while that response was in flight,
+        // retain at least the arrivals beyond the captured baseline.
+        unreadCount: Math.max(
+          0,
+          canonicalUnreadCount,
+          item.unreadCount - cutoff.unreadCount
+        )
+      }));
       emit();
     },
     setUnreadCount(id, count) {
-      conversations = normalizeConversations(
-        conversations.map(
-          (item) => item.conversation.id === id ? { ...item, unreadCount: Math.max(0, count) } : item
-        )
-      );
+      replaceOneSummary(id, (item) => ({ ...item, unreadCount: Math.max(0, count) }));
       emit();
     }
   };
@@ -1338,21 +1404,57 @@ function createMessagingEngine(options) {
   const conversationPageSize = options.conversationPageSize ?? 30;
   const messagePageSize = options.messagePageSize ?? 50;
   const openChannels = /* @__PURE__ */ new Map();
+  const channelReadiness = /* @__PURE__ */ new Map();
+  const settleChannelReadiness = /* @__PURE__ */ new Map();
+  const readReceiptTails = /* @__PURE__ */ new Map();
+  const persistedReadAt = /* @__PURE__ */ new Map();
+  const initialReadDepth = /* @__PURE__ */ new Map();
+  const initialReadGeneration = /* @__PURE__ */ new Map();
+  const initialReadChanges = /* @__PURE__ */ new Map();
   let inboxChannel = null;
   let conversationCursor = null;
   let disposed = false;
   function report(event) {
     options.onDiagnostic?.(event);
   }
-  function reportError(error, operation) {
+  function reportError(error, operation, context = {}) {
     const normalized = normalizeMessagingError(error, operation);
     report({
       // A missing session is a NORMAL lifecycle moment, not a red error. This
       // one line is the cure for "909 captured errors in 0.6s".
       level: normalized.code === "session-unavailable" ? "warn" : "error",
       message: normalized.message,
-      remedy: normalized.remedy
+      remedy: normalized.remedy,
+      code: normalized.code,
+      operation,
+      isRetryable: normalized.isRetryable,
+      error: normalized,
+      ...context
     });
+    return normalized;
+  }
+  function persistRead(id, isLive = () => true) {
+    const run = async () => {
+      if (!isLive()) return;
+      const at = store.snapshot().threads.get(id)?.latestAt ?? null;
+      if (at === null || (persistedReadAt.get(id) ?? "") >= at) return;
+      const cutoff = store.captureConversationRead(id, at);
+      try {
+        const canonicalUnreadCount = await repository.markRead(id, at);
+        if (!isLive()) return;
+        persistedReadAt.set(id, at);
+        store.markConversationRead(id, cutoff, canonicalUnreadCount);
+      } catch (error) {
+        throw reportError(error, "markRead", { conversationId: id });
+      }
+    };
+    const previous = readReceiptTails.get(id);
+    const current = previous === void 0 ? run() : previous.catch(() => void 0).then(run);
+    readReceiptTails.set(id, current);
+    void current.finally(() => {
+      if (readReceiptTails.get(id) === current) readReceiptTails.delete(id);
+    }).catch(() => void 0);
+    return current;
   }
   const outbox = createOutbox({
     ...options.outboxStorage !== void 0 ? { storage: options.outboxStorage } : {},
@@ -1437,6 +1539,137 @@ function createMessagingEngine(options) {
       reportError(error, "backfillConversation");
     }
   }
+  function applyLiveMessageChange(id, change) {
+    if ((initialReadDepth.get(id) ?? 0) > 0) {
+      const changes = initialReadChanges.get(id) ?? [];
+      changes.push(change);
+      initialReadChanges.set(id, changes);
+    }
+    if (change.kind === "delete") {
+      store.removeMessage(id, change.messageId);
+    } else {
+      store.ingest(change.message);
+    }
+  }
+  function beginInitialRead(id) {
+    const generation = (initialReadGeneration.get(id) ?? 0) + 1;
+    initialReadGeneration.set(id, generation);
+    initialReadDepth.set(id, (initialReadDepth.get(id) ?? 0) + 1);
+    initialReadChanges.set(id, initialReadChanges.get(id) ?? []);
+    return generation;
+  }
+  function finishInitialRead(id) {
+    const depth = (initialReadDepth.get(id) ?? 1) - 1;
+    if (depth > 0) {
+      initialReadDepth.set(id, depth);
+      return;
+    }
+    initialReadDepth.delete(id);
+    initialReadChanges.delete(id);
+  }
+  function openIsLive(id, generation, channel) {
+    return !disposed && initialReadGeneration.get(id) === generation && channel !== null && openChannels.get(id) === channel;
+  }
+  function installInitialPage(id, generation, page) {
+    if (initialReadGeneration.get(id) !== generation) return false;
+    const optimistic = (store.snapshot().threads.get(id)?.messages ?? []).filter(
+      (item) => item.deliveryState === "sending" || item.deliveryState === "failed"
+    );
+    const confirmedClientKeys = new Set(
+      page.items.flatMap(
+        (item) => item.clientMessageId === null ? [] : [item.clientMessageId]
+      )
+    );
+    store.setThread(id, page.items, { hasMoreOlder: page.hasMore });
+    for (const change of initialReadChanges.get(id) ?? []) {
+      if (change.kind === "delete") {
+        store.removeMessage(id, change.messageId);
+      } else {
+        store.ingest(change.message);
+      }
+    }
+    store.ingestMany(
+      optimistic.filter(
+        (item) => item.clientMessageId === null || !confirmedClientKeys.has(item.clientMessageId)
+      )
+    );
+    return true;
+  }
+  function ensureConversationChannel(id) {
+    const existing = openChannels.get(id);
+    if (existing !== void 0) {
+      return channelReadiness.get(id) ?? Promise.resolve(existing.status() === "connected");
+    }
+    let markReady;
+    const ready = new Promise((resolve) => {
+      markReady = resolve;
+    });
+    const handle = manager.open({
+      topic: conversationTopic(id),
+      // Presence callbacks are JOIN-TIME in supabase-js. Declare the read-only
+      // room shape on the first holder so later holders do not create a gap.
+      presence: { publish: false, state: {} },
+      postgresChanges: [
+        {
+          event: "*",
+          schema: "communication",
+          table: "dm_messages",
+          filter: `conversation_id=eq.${id}`,
+          rowId: (row) => typeof row["id"] === "string" ? row["id"] : void 0,
+          fingerprint: (row) => typeof row["content"] === "string" ? row["content"] : void 0,
+          updatedAtField: "updated_at",
+          updatedByField: "updated_by",
+          onChange: ({ payload, row }) => {
+            if (row === null) return;
+            if (payload?.eventType === "DELETE" || typeof row["deleted_at"] === "string" && row["deleted_at"].length > 0) {
+              const rawId = row["id"];
+              if (typeof rawId !== "string" || rawId.length === 0) {
+                reportError(
+                  new Error("A message deletion payload carried no message id."),
+                  "conversationMessageDelete",
+                  { conversationId: id }
+                );
+                return;
+              }
+              applyLiveMessageChange(id, {
+                kind: "delete",
+                messageId: asMessageId(rawId)
+              });
+              return;
+            }
+            const message = projectMessage(row, identity.organizationId);
+            applyLiveMessageChange(id, { kind: "upsert", message });
+          }
+        }
+      ],
+      broadcast: [
+        {
+          event: MESSAGING_EVENTS.message,
+          onMessage: ({ data }) => {
+            try {
+              const message = projectBroadcastMessage(data);
+              applyLiveMessageChange(id, { kind: "upsert", message });
+            } catch (error) {
+              reportError(error, "broadcastMessage");
+            }
+          }
+        }
+      ],
+      onStatusChange: (status) => {
+        if (status === "connected") markReady?.(true);
+        if (status === "disconnected") markReady?.(false);
+      },
+      onBackfill: () => {
+        void backfillConversation(id);
+        outbox.flush();
+      }
+    });
+    openChannels.set(id, handle);
+    channelReadiness.set(id, ready);
+    settleChannelReadiness.set(id, (connected) => markReady?.(connected));
+    if (handle.status() === "connected") markReady?.(true);
+    return ready;
+  }
   const engine = {
     store,
     outbox,
@@ -1462,7 +1695,9 @@ function createMessagingEngine(options) {
             onChange: ({ row }) => {
               if (row === null) return;
               const message = projectMessage(row, identity.organizationId);
-              const known = store.snapshot().conversations.some((item) => item.conversation.id === message.conversationId);
+              const known = store.snapshot().conversationSummaries.has(
+                message.conversationId
+              );
               if (!known) {
                 void reloadInbox().catch((error) => reportError(error, "inboxRefresh"));
                 return;
@@ -1470,6 +1705,9 @@ function createMessagingEngine(options) {
               store.ingest(message);
               const isMine = message.senderId === identity.userId;
               store.applyLastMessage(message, { incrementUnread: !isMine });
+              if (!isMine && store.snapshot().activeConversationId === message.conversationId) {
+                void persistRead(message.conversationId).catch(() => void 0);
+              }
               if (!isMine) options.onIncoming?.(message);
             }
           },
@@ -1534,18 +1772,35 @@ function createMessagingEngine(options) {
     },
     async openConversation(id) {
       store.setActiveConversation(id);
+      const generation = beginInitialRead(id);
+      let ownedChannel = null;
       try {
+        const connected = await ensureConversationChannel(id);
+        ownedChannel = openChannels.get(id) ?? null;
+        if (!connected || !openIsLive(id, generation, ownedChannel)) return;
         const page = await repository.listMessages(id, { limit: messagePageSize });
-        if (page.items.length === 0) {
-          await repository.getConversation(id);
-        }
+        if (!openIsLive(id, generation, ownedChannel)) return;
+        if (!installInitialPage(id, generation, page)) return;
+        const missingSummary = !store.snapshot().conversationSummaries.has(id);
+        const directSummary = missingSummary ? await repository.getConversationSummary(id) : null;
+        if (!openIsLive(id, generation, ownedChannel)) return;
         store.setConversationReadFailure(id, null);
-        store.setThread(id, page.items, { hasMoreOlder: page.hasMore });
+        if (directSummary !== null) store.setConversationSummary(directSummary);
+        await persistRead(
+          id,
+          () => openIsLive(id, generation, ownedChannel)
+        ).catch(() => void 0);
       } catch (error) {
+        if (!openIsLive(id, generation, ownedChannel)) return;
         const normalized = normalizeMessagingError(error, "openConversation");
         const unavailable = normalized.code === "not-found" || normalized.code === "forbidden";
         store.setConversationReadFailure(id, { error: normalized, unavailable });
         if (unavailable) {
+          openChannels.get(id)?.close();
+          openChannels.delete(id);
+          settleChannelReadiness.delete(id);
+          channelReadiness.delete(id);
+          store.clearThread(id);
           report({
             level: "warn",
             message: normalized.message,
@@ -1554,53 +1809,17 @@ function createMessagingEngine(options) {
           return;
         }
         reportError(normalized, "openConversation");
+      } finally {
+        finishInitialRead(id);
       }
-      if (openChannels.has(id) || disposed) return;
-      const handle = manager.open({
-        topic: conversationTopic(id),
-        // Presence callbacks are JOIN-TIME in supabase-js. Declare the
-        // read-only room shape on the first holder (the engine) so the
-        // composer/typist/online hooks can attach without forcing a rebuild
-        // after this durable channel has already subscribed.
-        presence: { publish: false, state: {} },
-        postgresChanges: [
-          {
-            event: "*",
-            schema: "communication",
-            table: "dm_messages",
-            filter: `conversation_id=eq.${id}`,
-            rowId: (row) => typeof row["id"] === "string" ? row["id"] : void 0,
-            fingerprint: (row) => typeof row["content"] === "string" ? row["content"] : void 0,
-            updatedAtField: "updated_at",
-            updatedByField: "updated_by",
-            onChange: ({ row }) => {
-              if (row === null) return;
-              store.ingest(projectMessage(row, identity.organizationId));
-            }
-          }
-        ],
-        broadcast: [
-          {
-            event: MESSAGING_EVENTS.message,
-            onMessage: ({ data }) => {
-              try {
-                store.ingest(projectBroadcastMessage(data));
-              } catch (error) {
-                reportError(error, "broadcastMessage");
-              }
-            }
-          }
-        ],
-        onBackfill: () => {
-          void backfillConversation(id);
-          outbox.flush();
-        }
-      });
-      openChannels.set(id, handle);
     },
     closeConversation(id) {
+      initialReadGeneration.set(id, (initialReadGeneration.get(id) ?? 0) + 1);
       openChannels.get(id)?.close();
       openChannels.delete(id);
+      settleChannelReadiness.get(id)?.(false);
+      settleChannelReadiness.delete(id);
+      channelReadiness.delete(id);
       if (store.snapshot().activeConversationId === id) {
         store.setActiveConversation(null);
       }
@@ -1652,12 +1871,7 @@ function createMessagingEngine(options) {
       }
     },
     async markRead(id) {
-      store.markConversationRead(id);
-      try {
-        await repository.markRead(id);
-      } catch (error) {
-        reportError(error, "markRead");
-      }
+      await persistRead(id);
     },
     async startDirectConversation(otherUserId) {
       const id = await repository.getOrCreateDirectConversation(otherUserId);
@@ -1666,9 +1880,15 @@ function createMessagingEngine(options) {
     },
     dispose() {
       disposed = true;
+      openChannels.forEach((_handle, id) => {
+        initialReadGeneration.set(id, (initialReadGeneration.get(id) ?? 0) + 1);
+      });
       outbox.dispose();
       openChannels.forEach((handle) => handle.close());
       openChannels.clear();
+      settleChannelReadiness.forEach((settle) => settle(false));
+      settleChannelReadiness.clear();
+      channelReadiness.clear();
       inboxChannel?.close();
       inboxChannel = null;
     }
@@ -1925,6 +2145,7 @@ var RPCS = {
   isParticipant: "is_dm_participant"
 };
 var MESSAGE_COLUMNS = "id,conversation_id,sender_id,organization_id,content,message_type,status,reply_to_id,client_message_id,action_data,media_url,media_thumbnail_url,media_metadata,created_at,edited_at,deleted_at,deleted_for_everyone,metadata";
+var PARTICIPANT_COLUMNS = "conversation_id,user_id,role,joined_at,last_read_at,is_muted,is_archived";
 var CONVERSATION_COLUMNS = "id,type,group_name,group_image_url,created_by,organization_id,created_at,updated_at,metadata";
 function optionalOrg(organizationId) {
   return typeof organizationId === "string" && organizationId.length > 0 ? organizationId : null;
@@ -1994,6 +2215,14 @@ function createMessagingRepository(options) {
   function actingUser(operation) {
     return withSessionRetry(operation, () => actingUserId());
   }
+  async function updateLiveParticipant(operation, conversationId, userId, patch) {
+    const destination = await organizationOfExisting(conversationId);
+    const { data, error } = await db().from(TABLES.participants).update({ ...patch, organization_id: destination }).eq("conversation_id", conversationId).eq("user_id", userId).eq("organization_id", destination).is("deleted_at", null).select("id").maybeSingle();
+    if (error !== null) throw normalizeMessagingError(error, operation);
+    if (data === null) {
+      throw writeNotApplied(operation, "participant update returned no live row");
+    }
+  }
   async function rpc(fn, args, operation) {
     const { data, error } = await rpcDb().rpc(fn, args);
     if (error !== null) throw normalizeMessagingError(error, operation);
@@ -2016,6 +2245,33 @@ function createMessagingRepository(options) {
     });
     return found;
   }
+  async function allLiveParticipants(conversationId) {
+    const operation = "getConversationSummary";
+    const pageSize = 1e3;
+    const rows = [];
+    for (let from = 0; ; from += pageSize) {
+      const response = await withSessionRetry(
+        operation,
+        async () => db().from(TABLES.participants).select(PARTICIPANT_COLUMNS, { count: "exact" }).eq("conversation_id", conversationId).is("deleted_at", null).order("user_id", { ascending: true }).range(from, from + pageSize - 1)
+      );
+      if (response.error !== null) {
+        throw normalizeMessagingError(response.error, operation);
+      }
+      const total = response.count;
+      if (typeof total !== "number" || !Number.isInteger(total) || total < 0) {
+        throw invalidResponse(operation, "participant read returned no exact count");
+      }
+      const page = response.data ?? [];
+      rows.push(...page);
+      if (rows.length >= total) return rows;
+      if (page.length === 0) {
+        throw invalidResponse(
+          operation,
+          `participant read stopped at ${rows.length} of ${total}`
+        );
+      }
+    }
+  }
   const conversationOrganizations = /* @__PURE__ */ new Map();
   async function organizationOfExisting(conversationId) {
     const known = conversationOrganizations.get(conversationId);
@@ -2127,6 +2383,78 @@ function createMessagingRepository(options) {
       );
       return summary.conversation;
     },
+    async getConversationSummary(id) {
+      const operation = "getConversationSummary";
+      const me = await actingUser(operation);
+      const [conversationResult, participantRows, latestResult, unreadRaw] = await withSessionRetry(
+        operation,
+        () => Promise.all([
+          db().from(TABLES.conversations).select(CONVERSATION_COLUMNS).eq("id", id).single(),
+          allLiveParticipants(id),
+          db().from(TABLES.messages).select(MESSAGE_COLUMNS).eq("conversation_id", id).is("deleted_at", null).order("created_at", { ascending: false }).order("id", { ascending: false }).limit(1).maybeSingle(),
+          rpc(
+            RPCS.unreadCount,
+            { p_conversation_id: id, p_user_id: me },
+            operation
+          )
+        ])
+      );
+      if (conversationResult.error !== null) {
+        throw normalizeMessagingError(conversationResult.error, operation);
+      }
+      if (latestResult.error !== null) {
+        throw normalizeMessagingError(latestResult.error, operation);
+      }
+      const conversation = conversationResult.data;
+      if (conversation === null) {
+        throw invalidResponse(operation, `conversation ${id} returned no row`);
+      }
+      if (typeof unreadRaw !== "number" || !Number.isFinite(unreadRaw) || unreadRaw < 0) {
+        throw invalidResponse(operation, `${RPCS.unreadCount} returned ${JSON.stringify(unreadRaw)}`);
+      }
+      const participantIds = participantRows.flatMap((row) => {
+        const value = row["user_id"];
+        return typeof value === "string" && value.length > 0 ? [projectUserSummary({ user_id: value }).userId] : [];
+      });
+      const profiles = await getUsers(participantIds);
+      const participants = participantIds.map((userId) => {
+        const profile = profiles.get(userId);
+        return profile === void 0 ? {
+          user_id: userId,
+          display_name: userId
+        } : {
+          user_id: profile.userId,
+          display_name: profile.displayName,
+          email: profile.email,
+          avatar_url: profile.avatarUrl,
+          is_agent: profile.isAgent
+        };
+      });
+      const viewer = participantRows.find((row) => row["user_id"] === me);
+      const latest = latestResult.data;
+      return projectConversationSummary(
+        {
+          conversation_id: conversation["id"],
+          conversation_type: conversation["type"],
+          group_name: conversation["group_name"],
+          group_image_url: conversation["group_image_url"],
+          conversation_created_at: conversation["created_at"],
+          conversation_updated_at: conversation["updated_at"],
+          organization_id: conversation["organization_id"],
+          created_by: conversation["created_by"],
+          metadata: conversation["metadata"],
+          participants,
+          last_message_content: latest?.["content"] ?? null,
+          last_message_sender_id: latest?.["sender_id"] ?? null,
+          last_message_at: latest?.["created_at"] ?? null,
+          unread_count: Math.floor(unreadRaw),
+          is_muted: viewer?.["is_muted"] ?? false,
+          is_archived: viewer?.["is_archived"] ?? false
+        },
+        me,
+        org
+      );
+    },
     async listMessages(conversationId, args = {}) {
       const limit = args.limit ?? 50;
       const operation = "listMessages";
@@ -2272,8 +2600,22 @@ function createMessagingRepository(options) {
     async markRead(conversationId, at) {
       const operation = "markRead";
       const me = await actingUser(operation);
-      const { error } = await db().from(TABLES.participants).update({ last_read_at: at ?? (/* @__PURE__ */ new Date()).toISOString(), updated_by: me }).eq("conversation_id", conversationId).eq("user_id", me);
-      if (error !== null) throw normalizeMessagingError(error, operation);
+      await updateLiveParticipant(operation, conversationId, me, {
+        last_read_at: at,
+        updated_by: me
+      });
+      const unread = await withSessionRetry(
+        operation,
+        () => rpc(
+          RPCS.unreadCount,
+          { p_conversation_id: conversationId, p_user_id: me },
+          operation
+        )
+      );
+      if (typeof unread !== "number" || !Number.isFinite(unread) || unread < 0) {
+        throw invalidResponse(operation, `${RPCS.unreadCount} returned ${JSON.stringify(unread)}`);
+      }
+      return Math.floor(unread);
     },
     async setConversationFlags(conversationId, flags) {
       const operation = "setConversationFlags";
@@ -2281,8 +2623,7 @@ function createMessagingRepository(options) {
       const patch = { updated_by: me };
       if (flags.isMuted !== void 0) patch["is_muted"] = flags.isMuted;
       if (flags.isArchived !== void 0) patch["is_archived"] = flags.isArchived;
-      const { error } = await db().from(TABLES.participants).update(patch).eq("conversation_id", conversationId).eq("user_id", me);
-      if (error !== null) throw normalizeMessagingError(error, operation);
+      await updateLiveParticipant(operation, conversationId, me, patch);
     },
     async addMembers(conversationId, memberIds) {
       const operation = "addMembers";
@@ -2302,14 +2643,18 @@ function createMessagingRepository(options) {
     async removeMember(conversationId, memberId) {
       const operation = "removeMember";
       const me = await actingUser(operation);
-      const { error } = await db().from(TABLES.participants).update({ deleted_at: (/* @__PURE__ */ new Date()).toISOString(), updated_by: me }).eq("conversation_id", conversationId).eq("user_id", memberId);
-      if (error !== null) throw normalizeMessagingError(error, operation);
+      await updateLiveParticipant(operation, conversationId, memberId, {
+        deleted_at: (/* @__PURE__ */ new Date()).toISOString(),
+        updated_by: me
+      });
     },
     async setMemberRole(conversationId, memberId, role) {
       const operation = "setMemberRole";
       const me = await actingUser(operation);
-      const { error } = await db().from(TABLES.participants).update({ role, updated_by: me }).eq("conversation_id", conversationId).eq("user_id", memberId);
-      if (error !== null) throw normalizeMessagingError(error, operation);
+      await updateLiveParticipant(operation, conversationId, memberId, {
+        role,
+        updated_by: me
+      });
     },
     getUser(userId) {
       const operation = "getUser";