@pmate/chat-sdk 0.12.0-next.8 → 0.12.0-next.80

package/lib/runtime/chatSession.js

@@ -1,3 +1,14 @@
+import { asChatError } from "./chatError.js";
+import { scopedGroupDenial, isScopedGroupDenial } from "./groupDenial.js";
+import { threadChatError } from "./chatError.js";
+import { ConversationDirectory } from "./conversationDirectory.js";
+import { groupThreadId } from "./thread.js";
+import { GroupClient } from "./groupClient.js";
+import { isReadingControl } from "./readingContent.js";
+import { outgoingContent, validateConversation } from "./outgoingContent.js";
+import { projectMessageTimeline } from "./messageTimeline.js";
+import { projectConversationReading } from "./conversationReading.js";
+import { ReadCountsClient } from "./readCounts.js";
 import { WindowedTasks } from "./coalescer.js";
 import { MessageReadersClient } from "./messageReaders.js";
 import { MessageClient } from "./messageClient.js";
@@ -8,23 +19,48 @@ import { unreadInConversation } from "./readIndex.js";
 /** Owns all browser message clients. Hosts subscribe to stable thread snapshots. */
 export class ChatSession {
     options;
+    conversations;
     messages;
     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();
+    timelineDecoded = new WeakMap();
+    decodeTimeline = (message) => { if (!this.timelineDecoded.has(message))
+        this.timelineDecoded.set(message, this.options.decode(message)); return this.timelineDecoded.get(message); };
     historyEdges = new Map();
     earlierReads = new Map();
     off = [];
     globalListeners = new Set();
     globalSnapshot;
+    closedThread = { messages: [], timeline: [], outgoing: [], hasEarlier: false, resetVersion: 0, complete: false, unread: undefined, messageReading: {} };
+    closedSummary = { threads: [], unreadMessageCount: undefined, badgeCount: undefined, connection: "closed" };
     connectionState = "closed";
     catchUp;
+    readingAllowed = false;
+    readingListeners = new Set();
+    acceptedReading = new Set();
+    readingAccess;
     readingStarted = false;
+    readingStarting;
+    withdrawn = false;
+    revoking;
     closed = false;
     starting;
+    initializing;
     closing;
     constructor(options) {
         this.options = options;
@@ -36,20 +72,96 @@ export class ChatSession {
             if (shared.appId !== scope.appId || shared.profileId !== scope.profileId || (shared.accountId !== undefined && shared.accountId !== scope.accountId) || (shared.teamId !== undefined && shared.teamId !== scope.teamId))
                 throw new Error("CHAT_SESSION_SCOPE_MISMATCH");
         }
-        this.messages = new MessageClient(options.messages);
-        this.connection = options.sharedConnection ?? new ChatClient(options.connection);
-        this.reading = new ReadingClient({ ...options.reading, storageScope: JSON.stringify([scope.accountId, scope.teamId]) });
-        this.readers = new MessageReadersClient({ appId: scope.appId, profileId: scope.profileId, token: options.reading.sessionToken, scope, onError: options.onError, hubHttpUrl: options.reading.hubHttpUrl, fetch: options.reading.fetch });
-        this.sender = new DurableChatSender(this.connection, scope, options.onError);
+        this.messages = new MessageClient({ ...options.messages, onError: (error, thread) => {
+                if (thread && error?.status === 403)
+                    void this.conversationFailure(error, thread).then(failure => options.onError(failure));
+                else
+                    options.messages.onError?.(error, thread);
+            } });
+        this.conversations = new ConversationDirectory(scope, () => this.messages.scopeAccess());
+        this.connection = options.sharedConnection ?? new ChatClient({ ...options.connection, onReach: async (event) => {
+                const handled = await this.handleReach(event);
+                if (handled)
+                    return handled;
+                if (options.connection.onReach)
+                    return options.connection.onReach(event);
+                throw new Error("REACH_HANDLER_UNAVAILABLE");
+            } });
+        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: async (error, _threadId, signal) => {
+                    if (error?.status === 403 && options.messages.transport.authorizeScope) {
+                        try {
+                            await options.messages.transport.authorizeScope(signal ?? new AbortController().signal);
+                            this.assertOpen();
+                            if ((await this.messages.scopeAccess()).allowed)
+                                return true;
+                        }
+                        catch { }
+                    }
+                    void this.revokeAccess().catch(error => options.onError(error));
+                    return false;
+                } });
+            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)
+                    return true;
+                if (!options.reconcileOutgoing)
+                    throw new Error("OUTBOX_RECONCILIATION_UNAVAILABLE");
+                try {
+                    return await options.reconcileOutgoing(record, signal);
+                }
+                catch (error) {
+                    if ([401, 403].includes(error?.status ?? 0))
+                        await this.messages.revoke(record.threadId);
+                    throw error;
+                }
+            } });
         this.catchUp = new WindowedTasks(1000, error => { if (!this.closed)
             options.onError(error); });
+        this.countTasks = new WindowedTasks(50, error => { if (!this.closed)
+            options.onError(error); });
+        if (typeof window !== "undefined") {
+            const wake = () => {
+                if (typeof document !== "undefined" && document.hidden)
+                    return;
+                this.wakeCounts();
+                this.groups?.wake();
+                this.scheduleCatchUp();
+            };
+            for (const type of ["online", "focus", "pageshow"])
+                window.addEventListener(type, wake);
+            if (typeof document !== "undefined")
+                document.addEventListener("visibilitychange", wake);
+            this.off.push(() => {
+                for (const type of ["online", "focus", "pageshow"])
+                    window.removeEventListener(type, wake);
+                if (typeof document !== "undefined")
+                    document.removeEventListener("visibilitychange", wake);
+            });
+        }
+        this.off.push(this.messages.subscribeAccessRevoked(() => { if (!this.withdrawn && !this.closed)
+            void this.revokeAccess().catch(error => options.onError(error)); }));
         this.off.push(this.messages.subscribeAll(thread => this.publish(thread)));
-        this.off.push(this.sender.subscribe(() => this.publishAll()), this.reading.subscribe(() => this.publishAll()));
+        this.off.push(this.sender.subscribe(() => this.publishAll()), this.reading.subscribe(() => { this.publishAll(); if (this.readingAllowed)
+            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(() => this.sender.confirm([message.hash])).catch(error => { if (String(error).includes("MESSAGE_PROJECTION_CHANGED"))
+                    void this.messages.receive(decoded.threadId, [decoded]).then(async () => {
+                        if (!this.closed && this.readingStarted)
+                            this.reading.refresh();
+                        if (message.from === scope.profileId)
+                            await this.sender.confirm([message.hash]);
+                    }).catch(error => { if (String(error).includes("MESSAGE_PROJECTION_CHANGED"))
                         this.messages.invalidate(decoded.threadId);
                     else if (!this.closed)
                         options.onError(error); });
@@ -62,24 +174,124 @@ export class ChatSession {
             this.connectionState = state;
             this.publishGlobal();
             if (state === "connected") {
-                const since = Date.now();
-                this.catchUp.schedule("scope", () => this.messages.restore(since));
+                this.scheduleCatchUp();
                 if (this.readingStarted)
                     this.reading.refresh();
+                this.wakeCounts();
+                this.groups?.wake();
             }
         }));
     }
+    scheduleCatchUp() {
+        if (this.connectionState !== "connected" || this.closed || this.withdrawn)
+            return;
+        const since = Date.now();
+        this.catchUp.schedule("scope", async () => {
+            if (this.connectionState === "connected" && !this.closed && !this.withdrawn)
+                await this.messages.restore(since, this.options.activeThreadId);
+        });
+    }
     start() {
         this.assertOpen();
         return this.starting ??= (async () => {
-            await this.sender.initialize();
-            this.readingStarted = true;
-            await this.reading.start();
+            await this.initialize();
             this.assertOpen();
             await this.connection.connect();
         })().catch(error => { this.starting = undefined; throw error; });
     }
-    assertOpen() { if (this.closed)
+    /** Initializes local state and background reading sync without opening a
+     * second transport when the host already owns calls/presence. */
+    initialize() {
+        this.assertOpen();
+        return this.initializing ??= (async () => {
+            await this.sender.initialize();
+            this.assertOpen();
+            await this.startReading();
+            this.assertOpen();
+        })().catch(error => { this.initializing = undefined; throw error; });
+    }
+    startReading() {
+        if (this.readingStarted)
+            return Promise.resolve();
+        return this.readingStarting ??= (async () => {
+            const access = await this.messages.scopeAccess();
+            if (!access.allowed)
+                return;
+            this.assertOpen();
+            await this.reading.prepareTeam(this.options.messages.scope.teamId, access.version);
+            this.setReadingAllowed(true);
+            await this.reading.start();
+            this.assertOpen();
+            this.readingStarted = true;
+        })().finally(() => { this.readingStarting = undefined; });
+    }
+    /** One-time migration only: never establishes trusted history coverage. */
+    importLegacyMessages(threadId, messages) { this.assertOpen(); return this.messages.importLegacy(threadId, messages); }
+    getReadingSnapshot() { return this.closed || this.withdrawn || !this.readingAllowed ? undefined : this.reading.getSnapshot(); }
+    subscribeReading(listener) { if (this.closed || this.withdrawn)
+        return () => { }; this.readingListeners.add(listener); return () => { this.readingListeners.delete(listener); }; }
+    setReadingAllowed(allowed) {
+        if (this.readingAllowed === allowed)
+            return;
+        const previous = this.getReadingSnapshot();
+        this.readingAllowed = allowed;
+        if (previous !== this.getReadingSnapshot())
+            this.readingListeners.forEach(listener => listener());
+        this.publishAll();
+    }
+    readingAuthority() {
+        return this.readingAccess ??= this.messages.scopeAccess().then(access => { if (!access.allowed)
+            this.setReadingAllowed(false); return access; }).finally(() => { this.readingAccess = undefined; });
+    }
+    async authorizeReading() {
+        const access = await this.readingAuthority();
+        if (this.withdrawn || !access.allowed)
+            throw new Error("CHAT_ACCESS_REVOKED");
+        await this.reading.prepareTeam(this.options.messages.scope.teamId, access.version);
+        this.setReadingAllowed(true);
+    }
+    readingOperation(run, durable = true) {
+        if (this.closed || this.withdrawn)
+            return Promise.reject(new Error(this.withdrawn ? "CHAT_ACCESS_REVOKED" : "CHAT_SESSION_CLOSED"));
+        const task = (async () => {
+            await this.authorizeReading();
+            if (this.withdrawn)
+                throw new Error("CHAT_ACCESS_REVOKED");
+            if (!durable)
+                this.assertOpen();
+            const next = await run();
+            if (this.withdrawn || !(await this.readingAuthority()).allowed)
+                throw new Error("CHAT_ACCESS_REVOKED");
+            return next;
+        })();
+        if (durable) {
+            this.acceptedReading.add(task);
+            void task.finally(() => this.acceptedReading.delete(task)).catch(() => { });
+        }
+        return task;
+    }
+    refreshReading() {
+        if (this.closed || this.withdrawn)
+            return;
+        void this.authorizeReading().then(() => { if (!this.closed && !this.withdrawn)
+            this.reading.refresh(); }).catch(error => { if (!this.closed && !this.withdrawn)
+            this.options.onError(error); });
+    }
+    synchronizeReading(cursor, profileId) { return this.readingOperation(() => this.reading.synchronize(cursor, profileId), false); }
+    /** Explicit text-history acknowledgement; unheard audio stays unread. */
+    async markRead(threadId, messages) {
+        this.assertOpen();
+        const cached = messages ?? this.getSnapshot(threadId).timeline.flatMap(item => {
+            if (item.recalled || !item.message)
+                return [];
+            const candidate = this.options.readingCandidate?.(item.message);
+            return candidate ? [{ id: item.id, threadId, from: item.from, mine: item.mine, recalled: item.recalled, readPolicy: candidate.readPolicy }] : [];
+        });
+        return this.readingOperation(() => this.reading.markRead(threadId, cached));
+    }
+    updateReading(transform) { return this.readingOperation(() => this.reading.update(transform)); }
+    assertOpen() { if (this.withdrawn)
+        throw new Error("CHAT_ACCESS_REVOKED"); if (this.closed)
         throw new Error("CHAT_SESSION_CLOSED"); }
     async getMessages(threadId, options = {}) {
         this.assertOpen();
@@ -92,18 +304,31 @@ export class ChatSession {
             throw new Error("INVALID_MESSAGE_QUERY");
         // Explicit authoritative changes (for example history assignment) can invalidate
         // even a recently cached empty window. Keep this on the existing read surface.
-        if (options.refresh)
-            await this.messages.read(threadId, options.limit ?? 100, true);
+        const refreshed = options.refresh ? await this.messages.read(threadId, options.limit ?? 100, true) : undefined;
         if (options.all) {
             return this.readAll(threadId);
         }
-        const page = await (options.before ? this.messages.earlier(threadId, options.before, options.limit) : this.messages.read(threadId, options.limit));
-        await this.sender.confirm(page.messages.map(message => message.id));
+        const page = await (options.before ? this.messages.earlier(threadId, options.before, options.limit) : refreshed ?? this.messages.read(threadId, options.limit));
+        this.assertOpen();
+        await this.confirmMessages(page.messages);
+        if (this.initializing && !this.readingStarted && page.complete)
+            await this.startReading();
+        this.assertOpen();
         const edge = this.historyEdges.get(threadId);
         if (!options.before && page.complete && (!edge || edge.version !== page.resetVersion))
             this.rememberHistoryEdge(threadId, page);
         return page;
     }
+    async confirmMessages(messages) {
+        await this.sender.initialize();
+        // Only this profile can create its outgoing wire hashes. Keep the legacy
+        // fallback when a generic host has not supplied an author on stored rows.
+        const hashes = messages.filter(message => {
+            const from = message.from;
+            return typeof from !== "string" || !from || from === this.options.messages.scope.profileId;
+        }).map(message => message.id);
+        return hashes.length ? this.sender.confirm(hashes) : Promise.resolve();
+    }
     rememberHistoryEdge(threadId, page) {
         const first = page.messages[0];
         this.historyEdges.set(threadId, { before: first ? { timestamp: first.timestamp, id: first.id } : undefined, version: page.resetVersion, hasEarlier: page.hasEarlier });
@@ -113,7 +338,12 @@ export class ChatSession {
         if (running)
             return running;
         const task = (async () => {
-            const recent = await this.getMessages(threadId);
+            const cached = this.messages.getSnapshot(threadId), known = this.historyEdges.get(threadId);
+            // The earlier-page path validates its own durable scope and coverage.
+            // A known boundary does not require rereading/reconfirming the newest
+            // message bodies before loading older messages.
+            const recent = cached?.complete && known?.hasEarlier && known.version === cached.resetVersion
+                ? cached : await this.getMessages(threadId);
             if (!recent.complete)
                 throw new Error("MESSAGE_WINDOW_INCOMPLETE");
             const edge = this.historyEdges.get(threadId);
@@ -121,7 +351,8 @@ export class ChatSession {
                 return { ...recent, messages: [], hasEarlier: false };
             if (!edge.before)
                 throw new Error("MESSAGE_SYNC_NO_PROGRESS");
-            const page = await this.getMessages(threadId, { before: edge.before });
+            const page = await this.messages.earlier(threadId, edge.before, 100, true);
+            await this.confirmMessages(page.messages);
             this.assertOpen();
             this.rememberHistoryEdge(threadId, page);
             return page;
@@ -151,12 +382,18 @@ export class ChatSession {
                         break;
                     }
                     pages.push(page.messages);
+                    if (!page.complete)
+                        return { messages: pages.reverse().flat(), hasEarlier: true, complete: false, resetVersion: version };
                 }
                 if (restart)
                     continue;
-                return { messages: pages.reverse().flat(), hasEarlier: false, complete: true, resetVersion: version };
+                const result = { messages: pages.reverse().flat(), hasEarlier: false, complete: true, resetVersion: version };
+                await this.messages.expandWindow(threadId, result);
+                this.rememberHistoryEdge(threadId, result);
+                return result;
             }
             catch (error) {
+                this.assertOpen();
                 if ([401, 403].includes(error?.status ?? 0))
                     throw error;
                 if (String(error).includes("MESSAGE_PROJECTION_CHANGED"))
@@ -168,20 +405,322 @@ export class ChatSession {
         }
         throw new Error("MESSAGE_SYNC_RESET_REQUIRED");
     }
-    sendMessage(threadId, input) {
+    /** Reads trusted local group metadata immediately; SDK refreshes it in the background. */
+    async getGroup(thread, options = {}) {
+        this.assertOpen();
+        if (!this.groups)
+            throw new Error("GROUP_METADATA_UNAVAILABLE");
+        return this.groups.get(typeof thread === "string" ? await this.resolveConversation(thread) : 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(target, changes) {
+        const thread = typeof target === "string" ? await this.resolveConversation(target) : target;
+        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);
+    }
+    async dissolveGroup(target, options = {}) {
+        const thread = typeof target === "string" ? await this.resolveConversation(target) : target;
+        const previous = await this.getGroup(thread);
+        if (previous.status === "dissolved")
+            return previous;
+        if (previous.versionNumber >= Number.MAX_SAFE_INTEGER)
+            throw new Error("INVALID_GROUP_VERSION");
+        await this.sendMessage(thread, { groupDissolve: { expectedRevision: options.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");
+        if (typeof thread === "string" && Object.hasOwn(input, "body"))
+            return this.sendWire(thread, input, options.waitFor === "delivered");
+        return this.sendContent(thread, input, options.waitFor === "delivered");
+    }
+    sendWire(threadId, 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; });
+    }
+    async getConversation(target) {
+        this.assertOpen();
+        try {
+            return await this.conversations.create(target);
+        }
+        catch (error) {
+            if (error?.message !== "CHAT_ACCESS_REVOKED")
+                throw error;
+            await this.messages.authorizeScope();
+            this.assertOpen();
+            return this.conversations.create(target);
+        }
+    }
+    async sendContent(target, input, delivered) {
+        let thread = typeof target === "string" ? await this.resolveConversation(target) : target;
+        validateConversation(this.options.messages.scope, thread);
+        await this.conversations.put(thread);
+        this.assertOpen();
+        // Recipients are SDK-owned metadata, never an App-supplied roster.
+        if (thread.kind === "group" && !input.groupCreate && !input.groupUpdate && !input.groupDissolve) {
+            const group = await this.getGroup(thread);
+            if (group.status === "dissolved")
+                throw new Error("GROUP_DISSOLVED");
+            this.assertOpen();
+            thread = { ...thread, memberIds: group.memberIds };
+        }
+        const wire = outgoingContent(this.options.messages.scope, thread, input);
+        if (input.recall || input.reaction)
+            return this.sendControl({ ...thread, memberIds: wire.recipients }, wire, delivered);
+        return this.sendWire(thread.id, wire, delivered);
+    }
+    async resolveConversation(threadId) {
+        const known = await this.conversations.get(threadId);
+        if (known)
+            return known;
+        const inferred = this.getConversationTarget(threadId);
+        if (!inferred)
+            throw new Error("MESSAGE_CONVERSATION_UNKNOWN");
+        return inferred;
+    }
+    /** Validated target identity survives content redaction; no roster is exposed. */
+    getConversationTarget(threadId) {
+        const scope = this.options.messages.scope;
+        const snapshot = this.getSnapshot(threadId), group = snapshot.group;
+        if (group)
+            return { id: threadId, kind: "group", targetId: group.groupId, teamId: scope.teamId };
+        const infer = (row) => {
+            const kind = row.threadKind ?? row.body?.threadKind;
+            if ((kind !== "group" && kind !== "dm") || !row.to || !row.from)
+                return undefined;
+            const thread = { id: threadId, kind, targetId: kind === "group" || row.from === scope.profileId ? row.to : row.from, teamId: scope.teamId };
+            try {
+                validateConversation(scope, thread);
+                return thread;
+            }
+            catch {
+                return undefined;
+            }
+        };
+        for (const value of snapshot.messages) {
+            const thread = infer(value);
+            if (thread)
+                return thread;
+        }
+        // Older integrations may have a durable send but no registered target or indexed history yet.
+        for (const value of snapshot.outgoing) {
+            const thread = infer(value.message);
+            if (thread)
+                return thread;
+        }
+        return undefined;
+    }
+    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);
         this.assertOpen();
-        return this.sender.enqueue(threadId, input);
+        if (!result.resetRequired) {
+            const previous = this.countSnapshots.get(threadId);
+            if (!previous || previous.revision <= result.revision) {
+                this.publishCounts({ appId: result.appId, threadId, revision: result.revision, counts: { ...previous?.counts, [messageId]: result.total } });
+                this.counts?.changed(threadId, result.revision);
+            }
+        }
+        return result;
     }
-    getReaders(threadId, messageId, page = {}, signal) {
+    /** Resolve voice media uniformly; pending local bytes are loaded only on demand. */
+    async getVoiceAttachment(threadId, messageId) {
         this.assertOpen();
-        return this.readers.getReaders({ ...page, threadId, messageId }, signal);
+        const item = this.getSnapshot(threadId).timeline.find(item => item.id === messageId);
+        if (!item || item.recalled)
+            throw new Error("VOICE_ATTACHMENT_UNAVAILABLE");
+        const local = await this.sender.acquireVoice(messageId, threadId);
+        try {
+            this.assertOpen();
+        }
+        catch (error) {
+            local?.release();
+            throw error;
+        }
+        const stillVisible = this.getSnapshot(threadId).timeline.find(item => item.id === messageId);
+        if (!stillVisible || stillVisible.recalled) {
+            local?.release();
+            throw new Error("VOICE_ATTACHMENT_UNAVAILABLE");
+        }
+        if (local)
+            return local;
+        const current = this.getSnapshot(threadId).timeline.find(item => item.id === messageId);
+        const body = current?.message?.body;
+        const value = body?.content?.voice?.url;
+        if (!current || current.recalled || typeof value !== "string")
+            throw new Error("VOICE_ATTACHMENT_UNAVAILABLE");
+        const url = new URL(value);
+        if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
+            throw new Error("INVALID_VOICE_ATTACHMENT_URL");
+        return { url: value, release: () => { } };
     }
     retryMessage(messageId) { this.assertOpen(); return this.sender.retry(messageId); }
-    observeMessages(threadId, ids, event) {
+    observeMessages(threadId, ids, event, clientInstanceId) {
+        if (this.closed || this.withdrawn) {
+            if (event === "receipts" && !threadId)
+                return Promise.resolve();
+            return Promise.reject(new Error(this.withdrawn ? "CHAT_ACCESS_REVOKED" : "CHAT_SESSION_CLOSED"));
+        }
+        if (event === "receipts") {
+            this.watchCounts(threadId, ids, clientInstanceId);
+            return Promise.resolve();
+        }
+        if (!threadId)
+            throw new Error("INVALID_READING_THREAD");
+        return this.readingOperation(() => event === "played" ? this.reading.recordExplicit(threadId, ids) : this.reading.recordVisible(threadId, ids));
+    }
+    /** Bridge transports can delegate social events without maintaining clients. */
+    async handleReach(event) {
         this.assertOpen();
-        return event === "played" ? this.reading.recordExplicit(threadId, ids) : this.reading.recordVisible(threadId, ids);
+        if (!["social.readCountsChanged", "social.readStateChanged"].includes(event.eventType))
+            return undefined;
+        if (event.appId !== this.options.messages.scope.appId)
+            throw new Error("UNEXPECTED_READING_APPLICATION");
+        if (event.eventType === "social.readCountsChanged") {
+            if (typeof event.payload.threadId !== "string" || !Number.isSafeInteger(event.payload.revision) || Number(event.payload.revision) < 0)
+                throw new Error("INVALID_READ_COUNTS_EVENT");
+            this.counts?.changed(event.payload.threadId, Number(event.payload.revision));
+        }
+        else {
+            if (typeof event.payload.syncCursor !== "string" || !/^v1:\d+$/.test(event.payload.syncCursor) || typeof event.payload.profileId !== "string")
+                throw new Error("INVALID_READING_EVENT");
+            if (event.payload.profileId !== this.options.messages.scope.profileId)
+                throw new Error("Reading reach identity mismatch");
+            await this.initialize();
+            await this.synchronizeReading(event.payload.syncCursor, event.payload.profileId);
+            this.assertOpen();
+        }
+        return "handled";
+    }
+    wakeCounts() {
+        if (this.counts && this.countsThread && !this.closed)
+            this.countTasks.schedule("counts", async () => { this.counts?.reconnect(); });
+    }
+    publishCountSnapshot(thread) {
+        const previous = this.snapshots.get(thread);
+        if (!previous) {
+            this.publish(thread, false);
+            return;
+        }
+        // Receipt-only updates never serialize or rebuild message bodies.
+        this.snapshots.set(thread, { ...previous, readCounts: this.countSnapshots.get(thread) });
+        this.listeners.get(thread)?.forEach(listener => listener());
+    }
+    publishCounts(value) {
+        if (this.closed || this.withdrawn)
+            return;
+        const previous = this.countSnapshots.get(value.threadId);
+        if ((previous && previous.revision > value.revision) || JSON.stringify(previous) === JSON.stringify(value))
+            return;
+        this.countSnapshots.delete(value.threadId);
+        this.countSnapshots.set(value.threadId, value);
+        if (this.countSnapshots.size > 128) {
+            const oldest = this.countSnapshots.keys().next().value;
+            this.countSnapshots.delete(oldest);
+            this.publishCountSnapshot(oldest);
+        }
+        this.publishCountSnapshot(value.threadId);
+    }
+    watchCounts(threadId, ids, receiver = this.connection.identityScope().clientInstanceId) {
+        if (!threadId || !ids.length) {
+            this.countsThread = undefined;
+            this.counts?.watch(undefined, []);
+            return;
+        }
+        if (!receiver || receiver.length > 512 || /[\x00-\x1f]/.test(receiver))
+            throw new Error("INVALID_READ_COUNTS_RECEIVER");
+        if (!this.counts || this.countsReceiver !== receiver) {
+            if (this.counts) {
+                const closing = this.counts.close().finally(() => this.countClosings.delete(closing));
+                this.countClosings.add(closing);
+            }
+            const scope = this.options.messages.scope;
+            const client = new ReadCountsClient({ appId: scope.appId, profileId: scope.profileId, scope, access: () => this.messages.scopeAccess(), token: this.options.reading.sessionToken, clientInstanceId: receiver, hubHttpUrl: this.options.reading.hubHttpUrl, fetch: this.options.reading.fetch,
+                onChange: value => { if (!this.closed && this.counts === client)
+                    this.publishCounts(value); },
+                onError: error => {
+                    if (this.closed || this.counts !== client)
+                        return;
+                    if (/READ_COUNTS_HTTP_(401|403)|RESPONSE_CACHE_(ACCESS_REVOKED|SCOPE_CHANGED|INVALIDATED)/.test(String(error))) {
+                        const threads = [...this.countSnapshots.keys()];
+                        this.countSnapshots.clear();
+                        threads.forEach(thread => this.publishCountSnapshot(thread));
+                    }
+                    this.options.onError(error);
+                } });
+            this.counts = client;
+            this.countsReceiver = receiver;
+        }
+        this.countsThread = threadId;
+        this.counts.watch(threadId, ids);
     }
     getSnapshot(threadId) {
+        if (this.closed || this.withdrawn) {
+            if (threadId === undefined)
+                return this.closedSummary;
+            return this.closedThread;
+        }
         if (threadId === undefined) {
             if (!this.globalSnapshot)
                 this.globalSnapshot = this.buildGlobal();
@@ -189,56 +728,121 @@ export class ChatSession {
         }
         let snapshot = this.snapshots.get(threadId);
         if (!snapshot) {
-            const messages = this.messages.getSnapshot(threadId);
-            const state = this.reading.getSnapshot();
-            snapshot = { messages: messages?.messages ?? [], hasEarlier: messages?.hasEarlier ?? false, resetVersion: messages?.resetVersion ?? 0, complete: messages?.complete ?? false, outgoing: this.sender.snapshot(threadId), unread: state?.threads.some(thread => (thread.conversationId ?? thread.id) === threadId) ? unreadInConversation(state, threadId) : { unreadMessageCount: 0, unreadMentionCount: 0, badgeCount: 0 } };
+            snapshot = this.buildThreadSnapshot(threadId);
             this.snapshots.set(threadId, snapshot);
         }
         return snapshot;
     }
-    subscribe(target, listener) {
-        this.assertOpen();
+    buildThreadSnapshot(threadId, previous) {
+        const source = this.messages.getSnapshot(threadId), raw = source?.messages ?? [];
+        const messages = previous && previous.messages.length === raw.length && previous.messages.every((message, index) => message === raw[index]) ? previous.messages : raw;
+        const outgoing = this.sender.snapshot(threadId);
+        const sameSource = previous && previous.messages === messages && previous.outgoing.length === outgoing.length && previous.outgoing.every((record, index) => record === outgoing[index]);
+        const candidates = new Map(messages.flatMap(message => { const candidate = this.options.readingCandidate?.(message); return candidate ? [[candidate.id, candidate]] : []; }));
+        const semanticReading = previous?.messageReading ?? {};
+        const semantics = sameSource ? previous.timeline : projectMessageTimeline({ appId: this.options.messages.scope.appId, profileId: this.options.messages.scope.profileId, threadId, messages, outgoing, candidates, decode: this.decodeTimeline, reading: semanticReading, previous: previous?.timeline });
+        for (const item of semantics)
+            if (item.recalled)
+                candidates.set(item.id, { ...candidates.get(item.id), id: item.id, threadId, from: item.from, mine: item.mine, recalled: true });
+        const state = this.getReadingSnapshot();
+        const kind = state?.threads.find(thread => (thread.conversationId ?? thread.id) === threadId)?.kind ?? "dm";
+        const view = projectConversationReading(state, { id: threadId, kind }, [...candidates.values()]);
+        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 { 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 (typeof target === "function") {
+            const notify = () => target(this.getSnapshot());
+            const off = this.subscribeChanges(notify);
+            try {
+                notify();
+            }
+            catch (error) {
+                off();
+                throw error;
+            }
+            return off;
+        }
+        const notify = () => listener(this.getSnapshot(target));
+        const off = this.subscribeChanges(target, notify, fields);
+        // The deprecated field-array form retains change-only behavior during migration.
+        if (!fields) {
+            try {
+                notify();
+            }
+            catch (error) {
+                off();
+                throw error;
+            }
+        }
+        return off;
+    }
+    subscribeChanges(target, listener, fields) {
+        if (this.closed || this.withdrawn)
+            return () => { };
         if (typeof target === "function") {
             this.globalListeners.add(target);
             return () => { this.globalListeners.delete(target); };
         }
         const threadId = target;
-        const notify = listener;
+        const selected = fields ? [...fields] : undefined;
+        let values = selected?.map(field => this.getSnapshot(threadId)[field]);
+        const equal = (a, b) => a === b || (Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((value, index) => value === b[index]));
+        const notify = selected ? () => {
+            const next = selected.map(field => this.getSnapshot(threadId)[field]);
+            const changed = next.some((value, index) => !equal(value, values[index]));
+            values = next;
+            if (changed)
+                listener();
+        } : listener;
         let listeners = this.listeners.get(threadId);
         if (!listeners) {
             listeners = new Set();
             this.listeners.set(threadId, listeners);
         }
         listeners.add(notify);
-        const off = this.messages.subscribe(threadId, () => { });
+        const off = this.messages.subscribe(threadId, () => { }), unpin = (!selected || selected.includes("group")) ? this.groups?.pin(threadId) : undefined;
         return () => {
             off();
+            unpin?.();
             listeners.delete(notify);
             if (!listeners.size)
                 this.listeners.delete(threadId);
         };
     }
     publishAll() {
+        if (this.closed || this.withdrawn)
+            return;
         for (const threadId of [...this.snapshots.keys()])
             this.publish(threadId, false);
         this.publishGlobal();
     }
     buildGlobal() {
         const ids = new Set(this.snapshots.keys());
-        for (const thread of this.reading.getSnapshot()?.threads ?? [])
+        for (const thread of this.getReadingSnapshot()?.threads ?? [])
             if (thread.teamId === this.options.messages.scope.teamId)
                 ids.add(thread.conversationId ?? thread.id);
         for (const outgoing of this.sender.snapshot())
             ids.add(outgoing.threadId);
         const threads = [...ids].sort().map(threadId => {
             const snapshot = this.getSnapshot(threadId);
-            return { threadId, lastMessage: snapshot.messages.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 };
         });
-        return { threads, unreadMessageCount: threads.reduce((sum, t) => sum + t.unread.unreadMessageCount, 0), badgeCount: threads.reduce((sum, t) => sum + t.unread.badgeCount, 0), connection: this.connectionState };
+        const state = this.getReadingSnapshot();
+        const known = Boolean(state && state.syncCursor !== "0" && threads.every(thread => thread.unread !== undefined));
+        return { threads, unreadMessageCount: known ? threads.reduce((sum, t) => sum + (t.unread?.unreadMessageCount ?? 0), 0) : undefined, badgeCount: known ? threads.reduce((sum, t) => sum + (t.unread?.badgeCount ?? 0), 0) : undefined, connection: this.connectionState };
     }
     publishGlobal() {
+        if (this.closed || this.withdrawn)
+            return;
         const next = this.buildGlobal();
-        if (JSON.stringify(next) === JSON.stringify(this.globalSnapshot))
+        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.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;
         this.globalListeners.forEach(listener => listener());
@@ -246,8 +850,9 @@ export class ChatSession {
     publish(threadId, notifyGlobal = true) {
         const previous = this.snapshots.get(threadId);
         this.snapshots.delete(threadId);
-        const next = this.getSnapshot(threadId);
-        if (previous && JSON.stringify(previous) === JSON.stringify(next)) {
+        const next = this.buildThreadSnapshot(threadId, previous);
+        this.snapshots.set(threadId, next);
+        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;
         }
@@ -255,21 +860,127 @@ export class ChatSession {
         if (notifyGlobal)
             this.publishGlobal();
     }
-    close() {
+    async conversationFailure(error, threadId) {
+        const failure = asChatError(error);
+        if (failure.code !== "access-denied" && failure.status !== 401)
+            return failure;
+        if (isScopedGroupDenial(error))
+            return scopedGroupDenial(threadChatError(error, threadId));
+        if (failure.status === 403 && this.active && this.options.messages.transport.authorizeScope) {
+            try {
+                await this.options.messages.transport.authorizeScope(new AbortController().signal);
+                this.assertOpen();
+                if ((await this.messages.scopeAccess()).allowed)
+                    return scopedGroupDenial(threadChatError(error, threadId));
+            }
+            catch { }
+        }
+        void this.revokeAccess().catch(error => this.options.onError(error));
+        return failure;
+    }
+    /** Withdraw one conversation without retiring sibling conversations. */
+    async revokeThread(threadId) { try {
+        await Promise.all([this.messages.revoke(threadId), this.groups?.revoke(threadId)]);
+    }
+    catch (error) {
+        void this.revokeAccess().catch(failure => this.options.onError(failure));
+        throw error;
+    } }
+    /** Permanently retire this identity/team session. UI withdrawal is immediate;
+     * completion means all durable stores have crossed the same authority epoch. */
+    revokeAccess() {
+        if (this.revoking)
+            return this.revoking;
+        if (this.closed)
+            return Promise.reject(new Error("CHAT_SESSION_CLOSED"));
+        this.withdrawn = true;
+        const knownThreads = [...new Set([...this.snapshots.keys(), ...this.historyEdges.keys()])];
+        this.catchUp.close();
+        this.countTasks.close();
+        this.off.splice(0).forEach(off => off());
+        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());
+        this.readingListeners.forEach(listener => listener());
+        if (!this.options.sharedConnection)
+            this.connection.close();
+        return this.revoking = Promise.resolve().then(async () => {
+            const failures = [];
+            let version;
+            try {
+                version = await this.messages.revokeScope();
+            }
+            catch (error) {
+                failures.push(error);
+                version = 1;
+                try {
+                    version = Math.max(1, (await this.messages.scopeAccess()).version);
+                }
+                catch (failure) {
+                    failures.push(failure);
+                }
+            }
+            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.groups?.retire(version), this.conversations.retire(version),
+            ]);
+            for (const result of results)
+                if (result.status === "rejected")
+                    failures.push(result.reason);
+            try {
+                await this.dispose();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+            if (failures.length)
+                throw new AggregateError(failures, "CHAT_ACCESS_CLEANUP_FAILED");
+        });
+    }
+    get active() { return !this.closed && !this.withdrawn; }
+    close() { return this.revoking ?? this.dispose(); }
+    dispose() {
         return this.closing ??= (async () => {
             this.closed = true;
             this.catchUp.close();
+            this.countTasks.close();
             this.off.splice(0).forEach(off => off());
             if (!this.options.sharedConnection)
                 this.connection.close();
-            this.readers.close();
-            await Promise.all([this.sender.close(), this.reading.close(), this.messages.close()]);
-            this.listeners.clear();
-            this.globalListeners.clear();
-            this.snapshots.clear();
-            this.historyEdges.clear();
-            this.earlierReads.clear();
-            this.globalSnapshot = undefined;
+            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(), this.conversations.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;
+            }
+            finally {
+                this.options.onDispose?.();
+                this.listeners.clear();
+                this.globalListeners.clear();
+                this.readingListeners.clear();
+                this.snapshots.clear();
+                this.timelineDecoded = new WeakMap();
+                this.countSnapshots.clear();
+                this.historyEdges.clear();
+                this.earlierReads.clear();
+                this.controlTails.clear();
+                this.globalSnapshot = undefined;
+            }
         })();
     }
 }