@pmate/chat-sdk 0.12.0-next.59 → 0.12.0-next.60

package/README.md

@@ -280,3 +280,31 @@ schema version 1; applications do not select storage formats or recovery steps.
 Pending voice snapshots contain `voiceAttachment` metadata, without loading audio bytes or creating Blob URLs at startup. For playback or transcription, acquire media through `await chat.getVoiceAttachment(threadId, messageId)`, use the returned `url`, and call `release()` when the consumer stops. The same method returns a remote voice reference for delivered messages. Attachment reads are charged before allocation, and close/revocation releases local URLs. A pending voice remains unread until the player actually starts; acquiring media does not mark it read.
 
 The outbox format upgrade renames the old canonical store without copying binary data in the schema transaction, then atomically separates inline payloads in bounded, resumable transactions. An already-open older application must reload; unsupported senders reject the new format. Original wire/hash, failed status and retry semantics are retained.
+
+
+Control messages use the same send API:
+
+```ts
+await chat.sendMessage(conversation, {recall: {messageId}})
+await chat.sendMessage(conversation, {reaction: {messageId, emojiId, active: true}})
+await chat.sendMessage(conversation, {invitation: {message: "Hello"}})
+await chat.sendMessage(group, {groupCreate: {title, members}})
+await chat.sendMessage(group, {groupUpdate: {expectedRevision, addMembers}})
+```
+
+These calls retain durable-acceptance semantics. Recall and reaction validate the target against the current scoped timeline or canonical local cache; the App does not supply protocol bodies or reaction versions. Reaction counters and exact wires commit in one IndexedDB transaction, including across documents. Validation ordering does not wait for each preceding commit, so a same-key burst still reaches the bounded acceptance batches. Pass `{waitFor:"delivered"}` as the third argument when an action requires server confirmation; the default still resolves after durable acceptance.
+
+
+Group metadata uses the same identity, cache and subscriptions:
+
+```ts
+const group = await chat.getGroup(conversation)
+const off = chat.subscribe(conversation.id, () => {
+  renderGroup(chat.getSnapshot(conversation.id).group)
+}, ["group"])
+await chat.createGroup(conversation, {title, members})
+await chat.updateGroup(conversation, {title: "New title"})
+off()
+```
+
+Reads restore trusted IndexedDB metadata before background revalidation. Creation and updates wait for confirmed delivery and a causal server version, including newer concurrent revisions; Apps do not poll for an exact message hash. Group events and browser recovery share a 200ms window. At most four metadata requests run concurrently, with 128 queued requests, a five-second request timeout, and at most five read-after-write attempts. Per-scope persistent metadata is capped at 64 groups / 1MiB, with 128KiB records, 32-record write batches, conditional cross-document writes and bounded pruning. Cached metadata does not bypass scope withdrawal or server membership checks. Binary media remains on demand.

package/lib/runtime/chatSession.d.ts

@@ -1,3 +1,5 @@
+import { type ChatGroup } from "./groupClient.js";
+import type { SocialGroup } from "./socialReadClient.js";
 import { type ChatConversation, type OutgoingContent } from "./outgoingContent.js";
 import { type TimelineItem } from "./messageTimeline.js";
 import { type ReadingCandidate, type MessageReadingState } from "./conversationReading.js";
@@ -19,6 +21,7 @@ export type ChatSessionOptions<T extends StoredMessage> = {
     activeThreadId?: string;
     uploadVoice?: DurableSenderOptions["uploadVoice"];
     reconcileOutgoing?: DurableSenderOptions["reconcile"];
+    loadGroup?: (groupId: string, signal: AbortSignal) => Promise<SocialGroup>;
     reading: ReadingClientOptions;
     decode: (message: ChatRuntimeMessage) => T | undefined;
     readingCandidate?: (message: T) => ReadingCandidate | undefined;
@@ -31,6 +34,7 @@ export type ChatThreadSnapshot<T> = {
     hasEarlier: boolean;
     resetVersion: number;
     complete: boolean;
+    group?: ChatGroup;
     readCounts?: ReadCountsResult;
     unread: ReturnType<typeof unreadInConversation> | undefined;
     messageReading: Readonly<Record<string, MessageReadingState>>;
@@ -40,6 +44,7 @@ export type ChatSummarySnapshot<T> = {
         threadId: string;
         lastMessage?: T;
         lastItem?: TimelineItem<T>;
+        group?: ChatGroup;
         unread: ChatThreadSnapshot<T>["unread"];
         outgoingCount: number;
     }[];
@@ -54,12 +59,17 @@ export declare class ChatSession<T extends StoredMessage> {
     private connection;
     private reading;
     private readers;
+    private groups?;
     private counts?;
     private countsReceiver?;
     private countsThread?;
     private countSnapshots;
     private countClosings;
     private countTasks;
+    private controlTails;
+    private acceptedControls;
+    private controlCount;
+    private controlBytes;
     private sender;
     private listeners;
     private snapshots;
@@ -121,8 +131,28 @@ export declare class ChatSession<T extends StoredMessage> {
     private rememberHistoryEdge;
     private readEarlier;
     private readAll;
-    sendMessage(thread: ChatConversation, input: OutgoingContent): Promise<ChatRuntimeMessage>;
-    sendMessage(threadId: string, input: SendMessageInput): Promise<ChatRuntimeMessage>;
+    /** Reads trusted local group metadata immediately; SDK refreshes it in the background. */
+    getGroup(thread: ChatConversation, options?: {
+        refresh?: boolean;
+    }): Promise<ChatGroup>;
+    createGroup(thread: ChatConversation, content: {
+        title: string;
+        members: readonly string[];
+    }): Promise<ChatGroup>;
+    updateGroup(thread: ChatConversation, changes: {
+        expectedRevision?: string;
+        addMembers?: readonly string[];
+        removeMembers?: readonly string[];
+        title?: string;
+        avatar?: string;
+    }): Promise<ChatGroup>;
+    sendMessage(thread: ChatConversation, input: OutgoingContent, options?: {
+        waitFor?: "accepted" | "delivered";
+    }): Promise<ChatRuntimeMessage>;
+    sendMessage(threadId: string, input: SendMessageInput, options?: {
+        waitFor?: "accepted" | "delivered";
+    }): Promise<ChatRuntimeMessage>;
+    private sendControl;
     getReaders(threadId: string, messageId: string, page?: Omit<MessageReadersQuery, "threadId" | "messageId">, signal?: AbortSignal): Promise<import("./messageReaders.js").MessageReadersPage>;
     /** Resolve voice media uniformly; pending local bytes are loaded only on demand. */
     getVoiceAttachment(threadId: string, messageId: string): Promise<VoiceAttachmentLease>;

package/lib/runtime/chatSession.js

@@ -1,3 +1,6 @@
+import { groupThreadId } from "./thread.js";
+import { GroupClient } from "./groupClient.js";
+import { isReadingControl } from "./readingContent.js";
 import { outgoingContent } from "./outgoingContent.js";
 import { projectMessageTimeline } from "./messageTimeline.js";
 import { projectConversationReading } from "./conversationReading.js";
@@ -16,12 +19,17 @@ export class ChatSession {
     connection;
     reading;
     readers;
+    groups;
     counts;
     countsReceiver;
     countsThread;
     countSnapshots = new Map();
     countClosings = new Set();
     countTasks;
+    controlTails = new Map();
+    acceptedControls = new Set();
+    controlCount = 0;
+    controlBytes = 0;
     sender;
     listeners = new Map();
     snapshots = new Map();
@@ -70,6 +78,10 @@ export class ChatSession {
             } });
         this.reading = new ReadingClient({ ...options.reading, teamId: scope.teamId, storageScope: JSON.stringify([scope.accountId]), migrateLegacy: true, metadataOnly: true });
         this.readers = new MessageReadersClient({ appId: scope.appId, profileId: scope.profileId, token: options.reading.sessionToken, scope, access: () => this.messages.scopeAccess(), onError: options.onError, hubHttpUrl: options.reading.hubHttpUrl, fetch: options.reading.fetch });
+        if (options.loadGroup) {
+            this.groups = new GroupClient({ scope, access: () => this.messages.scopeAccess(), load: options.loadGroup, onError: options.onError, onDenied: () => { void this.revokeAccess().catch(error => options.onError(error)); } });
+            this.off.push(this.groups.subscribe(thread => this.publish(thread)));
+        }
         this.sender = new DurableChatSender(this.connection, scope, options.onError, { access: () => this.messages.scopeAccess(), uploadVoice: options.uploadVoice, reconcile: async (record, signal) => {
                 const cached = await this.messages.cachedMessage(record.threadId, record.message.hash);
                 if (cached && cached.from === scope.profileId && cached.to === record.message.to)
@@ -94,6 +106,7 @@ export class ChatSession {
                 if (typeof document !== "undefined" && document.hidden)
                     return;
                 this.wakeCounts();
+                this.groups?.wake();
                 this.scheduleCatchUp();
             };
             for (const type of ["online", "focus", "pageshow"])
@@ -114,6 +127,10 @@ export class ChatSession {
             this.readingListeners.forEach(listener => listener()); }));
         this.off.push(this.connection.watchMessages(message => {
             try {
+                const body = message.body;
+                if (body?.kind === "group" && body.payload?.appId === scope.appId && body.payload.teamId === scope.teamId && body.payload.groupId === message.to) {
+                    this.groups?.hint({ id: groupThreadId(scope.appId, message.to, scope.teamId), kind: "group", targetId: message.to, teamId: scope.teamId }, Number.isSafeInteger(body.payload.versionNumber) ? body.payload.versionNumber : undefined);
+                }
                 const decoded = options.decode(message);
                 if (decoded)
                     void this.messages.receive(decoded.threadId, [decoded]).then(async () => {
@@ -138,6 +155,7 @@ export class ChatSession {
                 if (this.readingStarted)
                     this.reading.refresh();
                 this.wakeCounts();
+                this.groups?.wake();
             }
         }));
     }
@@ -360,13 +378,89 @@ export class ChatSession {
         }
         throw new Error("MESSAGE_SYNC_RESET_REQUIRED");
     }
-    sendMessage(thread, input) {
+    /** Reads trusted local group metadata immediately; SDK refreshes it in the background. */
+    getGroup(thread, options = {}) {
+        this.assertOpen();
+        if (!this.groups)
+            throw new Error("GROUP_METADATA_UNAVAILABLE");
+        return this.groups.get(thread, options);
+    }
+    async createGroup(thread, content) {
+        this.assertOpen();
+        if (!this.groups)
+            throw new Error("GROUP_METADATA_UNAVAILABLE");
+        await this.sendMessage(thread, { groupCreate: content }, { waitFor: "delivered" });
+        return this.groups.after(thread, 1);
+    }
+    async updateGroup(thread, changes) {
+        const previous = await this.getGroup(thread);
+        if (previous.versionNumber >= Number.MAX_SAFE_INTEGER)
+            throw new Error("INVALID_GROUP_VERSION");
+        await this.sendMessage(thread, { groupUpdate: { ...changes, expectedRevision: changes.expectedRevision ?? previous.revision } }, { waitFor: "delivered" });
+        return this.groups.after(thread, previous.versionNumber + 1);
+    }
+    sendMessage(thread, input, options = {}) {
         this.assertOpen();
+        if (options.waitFor !== undefined && !["accepted", "delivered"].includes(options.waitFor))
+            throw new Error("INVALID_MESSAGE_WAIT");
         const threadId = typeof thread === "string" ? thread : thread.id;
         const wire = typeof thread === "string" ? input : outgoingContent(this.options.messages.scope, thread, input);
-        return this.sender.enqueue(threadId, wire).then(next => { if (this.withdrawn)
+        const delivered = options.waitFor === "delivered";
+        if (typeof thread !== "string" && (input.recall || input.reaction))
+            return this.sendControl({ id: thread.id, kind: thread.kind, targetId: thread.targetId, teamId: thread.teamId, memberIds: wire.recipients }, wire, delivered);
+        return (delivered ? this.sender.send(threadId, wire) : this.sender.enqueue(threadId, wire)).then(next => { if (this.withdrawn)
             throw new Error("CHAT_ACCESS_REVOKED"); return next; });
     }
+    sendControl(thread, wire, delivered = false) {
+        const content = wire.body.content;
+        const recall = content.recall, reaction = content.reaction;
+        const id = recall?.messageId ?? reaction.messageId, key = JSON.stringify([thread.id, id, reaction?.emojiId ?? "recall"]);
+        const bytes = JSON.stringify(wire).length * 3 + 1024;
+        if (this.controlCount >= 4096 || this.controlBytes + bytes > 64 * 1024 * 1024)
+            return Promise.reject(new Error("MESSAGE_CONTROL_BACKPRESSURE"));
+        this.controlCount++;
+        this.controlBytes += bytes;
+        const previous = this.controlTails.get(key) ?? Promise.resolve();
+        let delivery;
+        const validated = previous.catch(() => { }).then(async () => {
+            this.assertOpen();
+            const item = this.getSnapshot(thread.id).timeline.find(item => item.id === id);
+            const target = (item?.message ?? await this.messages.cachedMessage(thread.id, id));
+            this.assertOpen();
+            const scope = this.options.messages.scope, from = item?.from ?? target?.from, body = target?.body;
+            const wrongScope = target?.threadId !== thread.id || target.appId !== undefined && target.appId !== scope.appId || body?.content?.appId !== undefined && body.content.appId !== scope.appId || body?.threadKind !== undefined && body.threadKind !== thread.kind;
+            const unavailable = !target || !from || id.startsWith("local-") || target.recalled || item?.recalled || target.legacyDisplay?.kind === "system" || item?.status === "failed" || item?.status === "sending";
+            const ordinary = body && ["message", "quote"].includes(String(body.kind)) && !isReadingControl(body, scope.appId);
+            if (wrongScope || unavailable || !ordinary)
+                throw new Error("MESSAGE_CONTROL_TARGET_UNAVAILABLE");
+            if (recall && from !== scope.profileId)
+                throw new Error("MESSAGE_RECALL_NOT_OWNED");
+            if (thread.kind === "dm" && from !== scope.profileId && from !== thread.targetId || thread.kind === "group" && (!wire.recipients?.includes(scope.profileId) || !wire.recipients.includes(from)))
+                throw new Error("MESSAGE_CONTROL_TARGET_UNAVAILABLE");
+            if (reaction) {
+                let floor = 0;
+                const events = item?.reactionEvents ?? target.reactionEvents ?? target.legacyDisplay?.reactionEvents ?? [];
+                for (const event of events)
+                    if (event.from === scope.profileId && event.messageId === id && event.emojiId === reaction.emojiId && Number.isSafeInteger(event.revision) && event.revision > floor)
+                        floor = event.revision;
+                for (const record of this.sender.snapshot(thread.id)) {
+                    const envelope = record.message.body, event = envelope?.content?.reaction;
+                    if (record.message.from === scope.profileId && envelope?.content?.appId === scope.appId && event?.messageId === id && event.emojiId === reaction.emojiId && Number.isSafeInteger(event.revision) && event.revision > floor)
+                        floor = event.revision;
+                }
+                wire = { ...wire, reactionRevisionFloor: floor };
+            }
+            delivery = delivered ? this.sender.send(thread.id, wire) : this.sender.enqueue(thread.id, wire);
+            void delivery.catch(() => { });
+        });
+        const tail = validated.finally(() => { if (this.controlTails.get(key) === tail)
+            this.controlTails.delete(key); });
+        const task = tail.then(() => delivery).then(message => { if (this.withdrawn)
+            throw new Error("CHAT_ACCESS_REVOKED"); return message; }).finally(() => { this.controlCount--; this.controlBytes -= bytes; this.acceptedControls.delete(task); });
+        this.controlTails.set(key, tail);
+        this.acceptedControls.add(task);
+        return task;
+    }
     async getReaders(threadId, messageId, page = {}, signal) {
         this.assertOpen();
         const result = await this.readers.getReaders({ ...page, threadId, messageId }, signal);
@@ -546,7 +640,7 @@ export class ChatSession {
         const unread = previous && JSON.stringify(previous.unread) === JSON.stringify(view.unread) ? previous.unread : view.unread;
         const messageReading = previous && JSON.stringify(previous.messageReading) === JSON.stringify(view.messageReading) ? previous.messageReading : view.messageReading;
         const timeline = messageReading === semanticReading ? semantics : projectMessageTimeline({ appId: this.options.messages.scope.appId, profileId: this.options.messages.scope.profileId, threadId, messages, outgoing, candidates, decode: this.decodeTimeline, reading: messageReading, previous: previous?.timeline });
-        return { timeline, messages, hasEarlier: source?.hasEarlier ?? false, resetVersion: source?.resetVersion ?? 0, complete: source?.complete ?? false, outgoing, readCounts: this.countSnapshots.get(threadId), unread, messageReading };
+        return { group: this.groups?.snapshot(threadId).data, timeline, messages, hasEarlier: source?.hasEarlier ?? false, resetVersion: source?.resetVersion ?? 0, complete: source?.complete ?? false, outgoing, readCounts: this.countSnapshots.get(threadId), unread, messageReading };
     }
     subscribe(target, listener, fields) {
         if (this.closed || this.withdrawn)
@@ -572,9 +666,10 @@ export class ChatSession {
             this.listeners.set(threadId, listeners);
         }
         listeners.add(notify);
-        const off = this.messages.subscribe(threadId, () => { });
+        const off = this.messages.subscribe(threadId, () => { }), unpin = this.groups?.pin(threadId);
         return () => {
             off();
+            unpin?.();
             listeners.delete(notify);
             if (!listeners.size)
                 this.listeners.delete(threadId);
@@ -596,7 +691,7 @@ export class ChatSession {
             ids.add(outgoing.threadId);
         const threads = [...ids].sort().map(threadId => {
             const snapshot = this.getSnapshot(threadId);
-            return { threadId, lastMessage: snapshot.timeline.at(-1)?.message, lastItem: snapshot.timeline.at(-1), unread: snapshot.unread, outgoingCount: snapshot.outgoing.length };
+            return { threadId, group: snapshot.group, lastMessage: snapshot.timeline.at(-1)?.message, lastItem: snapshot.timeline.at(-1), unread: snapshot.unread, outgoingCount: snapshot.outgoing.length };
         });
         const state = this.getReadingSnapshot();
         const known = Boolean(state && state.syncCursor !== "0" && threads.every(thread => thread.unread !== undefined));
@@ -609,7 +704,7 @@ export class ChatSession {
         const previous = this.globalSnapshot;
         if (previous && previous.connection === next.connection && previous.unreadMessageCount === next.unreadMessageCount && previous.badgeCount === next.badgeCount && previous.threads.length === next.threads.length && previous.threads.every((thread, index) => {
             const other = next.threads[index];
-            return thread.threadId === other.threadId && thread.lastMessage === other.lastMessage && thread.lastItem === other.lastItem && thread.outgoingCount === other.outgoingCount && JSON.stringify(thread.unread) === JSON.stringify(other.unread);
+            return thread.threadId === other.threadId && thread.group === other.group && thread.lastMessage === other.lastMessage && thread.lastItem === other.lastItem && thread.outgoingCount === other.outgoingCount && JSON.stringify(thread.unread) === JSON.stringify(other.unread);
         }))
             return;
         this.globalSnapshot = next;
@@ -620,7 +715,7 @@ export class ChatSession {
         this.snapshots.delete(threadId);
         const next = this.buildThreadSnapshot(threadId, previous);
         this.snapshots.set(threadId, next);
-        if (previous && previous.messages === next.messages && previous.timeline === next.timeline && previous.outgoing.length === next.outgoing.length && previous.outgoing.every((record, index) => record === next.outgoing[index]) && previous.hasEarlier === next.hasEarlier && previous.resetVersion === next.resetVersion && previous.complete === next.complete && previous.readCounts === next.readCounts && JSON.stringify(previous.unread) === JSON.stringify(next.unread) && JSON.stringify(previous.messageReading) === JSON.stringify(next.messageReading)) {
+        if (previous && previous.group === next.group && previous.messages === next.messages && previous.timeline === next.timeline && previous.outgoing.length === next.outgoing.length && previous.outgoing.every((record, index) => record === next.outgoing[index]) && previous.hasEarlier === next.hasEarlier && previous.resetVersion === next.resetVersion && previous.complete === next.complete && previous.readCounts === next.readCounts && JSON.stringify(previous.unread) === JSON.stringify(next.unread) && JSON.stringify(previous.messageReading) === JSON.stringify(next.messageReading)) {
             this.snapshots.set(threadId, previous);
             return;
         }
@@ -643,12 +738,14 @@ export class ChatSession {
         this.sender.withdraw();
         this.reading.withdraw();
         this.readers.withdraw();
+        this.groups?.withdraw();
         this.counts?.watch(undefined, []);
         this.countSnapshots.clear();
         this.snapshots.clear();
         this.timelineDecoded = new WeakMap();
         this.historyEdges.clear();
         this.earlierReads.clear();
+        this.controlTails.clear();
         this.globalSnapshot = undefined;
         this.listeners.forEach(listeners => listeners.forEach(listener => listener()));
         this.globalListeners.forEach(listener => listener());
@@ -674,7 +771,7 @@ export class ChatSession {
             const results = await Promise.allSettled([
                 this.sender.revoke(version),
                 this.reading.revokeTeam(this.options.messages.scope.teamId, version, knownThreads),
-                this.readers.retireScope(version), this.counts?.retireScope(version),
+                this.readers.retireScope(version), this.counts?.retireScope(version), this.groups?.retire(version),
             ]);
             for (const result of results)
                 if (result.status === "rejected")
@@ -698,11 +795,11 @@ export class ChatSession {
             this.off.splice(0).forEach(off => off());
             if (!this.options.sharedConnection)
                 this.connection.close();
-            const senderClosing = this.sender.close();
-            const readingBarrier = Promise.allSettled([...this.acceptedReading]);
+            const senderClosing = this.sender.close(), groupsClosing = this.groups?.close();
+            const readingBarrier = Promise.allSettled([...this.acceptedReading, ...this.acceptedControls]);
             const readingClosing = readingBarrier.then(() => this.reading.close());
             try {
-                const results = await Promise.allSettled([this.counts?.close(), ...this.countClosings, this.readers.close(), senderClosing, readingClosing, this.messages.close(Promise.allSettled([senderClosing, readingBarrier]))]);
+                const results = await Promise.allSettled([this.counts?.close(), ...this.countClosings, this.readers.close(), groupsClosing, senderClosing, readingClosing, this.messages.close(Promise.allSettled([senderClosing, groupsClosing, readingBarrier]))]);
                 const failed = results.find((result) => result.status === "rejected");
                 if (failed)
                     throw failed.reason;
@@ -716,6 +813,7 @@ export class ChatSession {
                 this.countSnapshots.clear();
                 this.historyEdges.clear();
                 this.earlierReads.clear();
+                this.controlTails.clear();
                 this.globalSnapshot = undefined;
             }
         })();

package/lib/runtime/createChat.js

@@ -32,6 +32,7 @@ export function createChat(options) {
                 return true;
             });
         },
+        loadGroup: (groupId, signal) => reader.group({ groupId, teamId }, signal),
         activeThreadId: options.threadId,
         messages: { scope: { appId, accountId, profileId, teamId }, transport: { load: (thread, signal) => page(thread, signal), changes: (thread, after, signal) => page(thread, signal, { after }), older: (thread, before, signal) => page(thread, signal, { before }) }, onError },
         reading: { appId, profileId, sessionToken: token, hubHttpUrl: http, fetch: options.fetch, onError },

package/lib/runtime/durableSender.d.ts

@@ -28,7 +28,8 @@ export type SendMessageInput = {
     to: string;
     body: ChatBody;
     recipients?: string[];
-    voiceBlob?: Blob;
+    voiceBlob?: Blob; /** SDK-owned reaction sequencing, committed with the exact wire. */
+    reactionRevisionFloor?: number;
 };
 export type SenderScopeAccess = {
     version: number;
@@ -48,6 +49,7 @@ export declare class DurableChatSender {
     private options;
     private db;
     private outbox;
+    private controlRevisions;
     private attachments;
     private schemaReady;
     private attachmentBytes;

package/lib/runtime/durableSender.js

@@ -1,4 +1,5 @@
 import { Dexie } from "dexie";
+import { validMessageIdentifier } from "./outgoingContent.js";
 import { outboxDatabase, prepareOutboxSchema } from "./outboxSchema.js";
 import { blake3 } from "@noble/hashes/blake3.js";
 import { bytesToHex } from "@noble/hashes/utils.js";
@@ -11,6 +12,7 @@ export class DurableChatSender {
     options;
     db;
     outbox;
+    controlRevisions;
     attachments;
     schemaReady;
     attachmentBytes = 0;
@@ -62,6 +64,7 @@ export class DurableChatSender {
         this.db = outboxDatabase(factory, name);
         this.outbox = this.db.table("outgoingMessages");
         this.attachments = this.db.table("outgoingAttachments");
+        this.controlRevisions = this.db.table("outgoingControls");
         this.epochs = this.db.table("scopeEpochs");
         this.outbox.hook("creating", (_key, row) => { row.pendingState = row.confirmed ? 0 : 1; });
         this.outbox.hook("updating", (changes, _key, row) => ({ pendingState: (Object.hasOwn(changes, "confirmed") ? changes.confirmed : row.confirmed) ? 0 : 1 }));
@@ -110,7 +113,7 @@ export class DurableChatSender {
     async restore() {
         await this.schemaReady;
         const access = await this.readAccess();
-        const loaded = await this.db.transaction("rw", this.outbox, this.epochs, this.attachments, async () => {
+        const loaded = await this.db.transaction("rw", this.outbox, this.epochs, this.attachments, this.controlRevisions, async () => {
             const current = (await this.epochs.get(this.scope))?.version ?? 0;
             const version = access?.version ?? current;
             if (version < current)
@@ -136,7 +139,7 @@ export class DurableChatSender {
         let after;
         const restored = new Map();
         while (!this.closed && !this.withdrawn) {
-            const batch = await this.db.transaction("rw", this.outbox, this.epochs, this.attachments, async () => {
+            const batch = await this.db.transaction("rw", this.outbox, this.epochs, this.attachments, this.controlRevisions, async () => {
                 if (((await this.epochs.get(this.scope))?.version ?? 0) !== this.version)
                     throw new Error("OUTBOX_SCOPE_CHANGED");
                 const keys = await (loaded.legacy
@@ -213,7 +216,7 @@ export class DurableChatSender {
     async withEpoch(mode, operation) {
         await this.checkAccess();
         try {
-            return await this.db.transaction(mode, this.outbox, this.epochs, this.attachments, async () => {
+            return await this.db.transaction(mode, this.outbox, this.epochs, this.attachments, this.controlRevisions, async () => {
                 if (this.closed || this.withdrawn)
                     throw new Error("OUTBOX_ACCESS_REVOKED");
                 if (((await this.epochs.get(this.scope))?.version ?? 0) !== this.version)
@@ -230,6 +233,7 @@ export class DurableChatSender {
     async deleteRows() {
         await this.outbox.where("[scope+hash]").between([this.scope, Dexie.minKey], [this.scope, Dexie.maxKey], true, true).delete();
         await this.attachments.where("scope").equals(this.scope).delete();
+        await this.controlRevisions.where("scope").equals(this.scope).delete();
     }
     /** Stop disclosure immediately; durable invalidation is coordinated separately. */
     withdraw() {
@@ -253,7 +257,7 @@ export class DurableChatSender {
         return this.revoking = (async () => {
             await this.ready.catch(error => { if (!String(error).includes("OUTBOX_SCOPE_CHANGED"))
                 throw error; });
-            const version = await this.db.transaction("rw", this.outbox, this.epochs, this.attachments, async () => {
+            const version = await this.db.transaction("rw", this.outbox, this.epochs, this.attachments, this.controlRevisions, async () => {
                 const current = (await this.epochs.get(this.scope))?.version ?? 0;
                 const target = targetVersion ?? this.version + 1;
                 if (!Number.isSafeInteger(target) || target < 0)
@@ -298,6 +302,11 @@ export class DurableChatSender {
             return Promise.reject(new Error("OUTBOX_ACCESS_REVOKED"));
         if (input.voiceBlob && (!(input.voiceBlob instanceof Blob) || input.voiceBlob.size === 0 || input.voiceBlob.size > 16 * 1024 * 1024))
             return Promise.reject(new Error("INVALID_VOICE_ATTACHMENT"));
+        const reactionFloor = input.reactionRevisionFloor;
+        if (reactionFloor !== undefined && input.voiceBlob)
+            return Promise.reject(new Error("INVALID_MESSAGE_REACTION"));
+        if (reactionFloor !== undefined && (!Number.isSafeInteger(reactionFloor) || reactionFloor < 0 || reactionFloor >= Number.MAX_SAFE_INTEGER))
+            return Promise.reject(new Error("INVALID_REACTION_REVISION"));
         let bytes;
         try {
             bytes = JSON.stringify([input.to, input.body, input.recipients, this.identity]).length * 3 + 1024 + (input.voiceBlob?.size ?? 0);
@@ -317,6 +326,12 @@ export class DurableChatSender {
             const message = this.client.prepareChat(input.to, withChatTeam(input.body, this.identity.teamId), input.recipients);
             if (message.from !== this.identity.profileId)
                 throw new Error("OUTGOING_MESSAGE_IDENTITY_MISMATCH");
+            if (reactionFloor !== undefined) {
+                const body = message.body;
+                const reaction = body.kind === "message" ? body.content.reaction : undefined;
+                if (body.kind !== "message" || body.content.appId !== this.identity.appId || !reaction || reaction.version !== 1 || !validMessageIdentifier(reaction.messageId) || !validMessageIdentifier(reaction.emojiId) || typeof reaction.active !== "boolean")
+                    throw new Error("INVALID_MESSAGE_REACTION");
+            }
             const command = statefulGroup(message);
             if (command)
                 message.hash = commandId(this.scope, this.version, threadId, message);
@@ -327,7 +342,7 @@ export class DurableChatSender {
             }
             const record = { ...(input.voiceBlob ? { voiceData: { bytes: await input.voiceBlob.arrayBuffer(), type: input.voiceBlob.type } } : {}), scope: this.scope, threadId, hash: message.hash, message, status: "sending", accessVersion: this.version };
             const durable = await new Promise((resolve, reject) => {
-                this.acceptanceQueue.push({ record, bytes, resolve, reject });
+                this.acceptanceQueue.push({ record, reactionFloor, bytes, resolve, reject });
                 this.scheduleAcceptances();
             });
             return durable.message;
@@ -351,11 +366,11 @@ export class DurableChatSender {
             let bytes = 0, count = 0, operations = 0;
             for (const item of this.acceptanceQueue) {
                 const size = item.bytes;
-                if (operations + (hasVoice(item.record) ? 2 : 1) > 128 || (count > 0 && bytes + size > 20 * 1024 * 1024))
+                if (operations + (hasVoice(item.record) || item.reactionFloor !== undefined ? 2 : 1) > 128 || (count > 0 && bytes + size > 20 * 1024 * 1024))
                     break;
                 bytes += size;
                 count++;
-                operations += hasVoice(item.record) ? 2 : 1;
+                operations += hasVoice(item.record) || item.reactionFloor !== undefined ? 2 : 1;
             }
             const batch = this.acceptanceQueue.splice(0, count);
             try {
@@ -363,8 +378,20 @@ export class DurableChatSender {
                     const commands = batch.filter(item => statefulGroup(item.record.message));
                     const previous = await this.outbox.bulkGet(commands.map(item => [this.scope, item.record.hash]));
                     const known = new Map(previous.filter((row) => Boolean(row && (row.accessVersion ?? 0) === this.version)).map(row => [row.hash, row]));
-                    const writes = [], records = [];
-                    for (const { record } of batch) {
+                    const writes = [], records = [], revisions = new Map();
+                    for (const item of batch) {
+                        let record = item.record;
+                        if (item.reactionFloor !== undefined) {
+                            const body = record.message.body;
+                            const reaction = body.content.reaction;
+                            const key = [this.scope, record.threadId, reaction.messageId, reaction.emojiId], encoded = JSON.stringify(key);
+                            const previous = revisions.get(encoded) ?? await this.controlRevisions.get(key);
+                            const revision = Math.max(item.reactionFloor, previous?.version === this.version ? previous.value : 0) + 1;
+                            if (!Number.isSafeInteger(revision))
+                                throw new Error("INVALID_REACTION_REVISION");
+                            revisions.set(encoded, { scope: this.scope, threadId: record.threadId, target: reaction.messageId, emoji: reaction.emojiId, version: this.version, value: revision });
+                            record = { ...record, message: { ...record.message, body: { ...body, content: { ...body.content, reaction: { ...reaction, revision } } } } };
+                        }
                         const command = statefulGroup(record.message), old = command ? known.get(record.hash) : undefined;
                         if (old) {
                             if (old.message.from !== this.identity.profileId || old.message.hash !== record.hash || commandId(this.scope, this.version, record.threadId, old.message) !== record.hash)
@@ -381,6 +408,8 @@ export class DurableChatSender {
                     const split = writes.map(splitAttachment), payloads = split.flatMap(item => item.attachment ? [item.attachment] : []);
                     if (payloads.length)
                         await this.attachments.bulkPut(payloads);
+                    if (revisions.size)
+                        await this.controlRevisions.bulkPut([...revisions.values()]);
                     if (split.length)
                         await this.outbox.bulkPut(split.map(item => item.record));
                     const metadata = new Map(split.map(item => [item.record.hash, item.record]));

package/lib/runtime/groupClient.d.ts

@@ -0,0 +1,76 @@
+import { type ResponseCacheAccess } from "./responseCache.js";
+import { type MessageScope } from "./messageStore.js";
+import { type ChatConversation } from "./outgoingContent.js";
+import type { SocialGroup } from "./socialReadClient.js";
+export type ChatGroup = {
+    groupId: string;
+    teamId: string;
+    ownerId: string;
+    title: string;
+    avatar?: string;
+    memberIds: readonly string[];
+    revision: string;
+    versionNumber: number;
+};
+export type GroupSnapshot = {
+    data?: ChatGroup;
+    loading: boolean;
+    error?: unknown;
+};
+export type GroupClientOptions = {
+    scope: MessageScope;
+    access: ResponseCacheAccess;
+    load: (groupId: string, signal: AbortSignal) => Promise<SocialGroup>;
+    onError: (error: unknown) => void;
+    onDenied?: (error: unknown) => Promise<void> | void;
+    indexedDB?: IDBFactory;
+    name?: string;
+};
+/** SDK-owned roster cache. Read sources, concurrency and reconciliation stay private. */
+export declare class GroupClient {
+    private options;
+    private cache;
+    private entries;
+    private pins;
+    private listeners;
+    private localQueue;
+    private localScheduled;
+    private localRunning;
+    private tasks;
+    private authority?;
+    private version?;
+    private clock;
+    private active;
+    private queue;
+    private controllers;
+    private channel?;
+    private withdrawn;
+    private closed;
+    private closing?;
+    constructor(options: GroupClientOptions);
+    private assertOpen;
+    private checkAuthority;
+    private entry;
+    snapshot(threadId: string): GroupSnapshot;
+    subscribe(listener: (threadId: string) => void): () => void;
+    pin(threadId: string): () => void;
+    private publish;
+    private normalize;
+    private cached;
+    private local;
+    private flushLocal;
+    private reload;
+    get(thread: ChatConversation, options?: {
+        refresh?: boolean;
+    }): Promise<ChatGroup>;
+    private schedule;
+    wake(): void;
+    hint(thread: ChatConversation, versionNumber?: number): void;
+    private slot;
+    private drain;
+    private request;
+    after(thread: ChatConversation, minimumVersion: number): Promise<ChatGroup>;
+    withdraw(): void;
+    retire(version: number): Promise<void>;
+    close(): Promise<void>;
+}