@pmate/chat-sdk 0.12.0-next.23 → 0.12.0-next.25

package/README.md

@@ -228,3 +228,18 @@ Custom primitive integrations must initialize them with the same authenticated
 scope, dispose them on identity changes, and wire their transport to an authorized
 server. Standard browser integrations should use the facade instead. The Merry migration and production validation
 are tracked in the unified message layer proposal.
+
+When the browser reports offline, scheduled message restoration and reading
+refreshes wait for the normal reconnect/wake path. Cached reads remain available;
+unknown receipt counts stay unknown and an uncached reader detail page rejects
+without attempting transport. A network failure arriving after the browser went
+offline does not turn background synchronization into an operation error.
+Authorization failures still revoke the corresponding cached data.
+
+Reading entry points check the message scope even before `initialize()` finishes.
+Concurrent observations share the permission lookup and batch their local writes.
+Visibility/playback operations reject another known team's conversation; a
+permission change in another team does not discard this team's observations.
+Ordinary shutdown waits for accepted local reading writes, while access withdrawal
+rejects late results. Retired asynchronous reading entries reject through promises;
+refresh/subscription teardown remains safe.

package/lib/runtime/chatSession.d.ts

@@ -63,6 +63,10 @@ export declare class ChatSession<T extends StoredMessage> {
     private closedSummary;
     private connectionState;
     private catchUp;
+    private readingAllowed;
+    private readingListeners;
+    private acceptedReading;
+    private readingAccess?;
     private readingStarted;
     private readingStarting?;
     private withdrawn;
@@ -81,6 +85,10 @@ export declare class ChatSession<T extends StoredMessage> {
     importLegacyMessages(threadId: string, messages: T[]): Promise<void>;
     getReadingSnapshot(): import("./readIndex.js").ReadIndexState | undefined;
     subscribeReading(listener: () => void): () => void;
+    private setReadingAllowed;
+    private readingAuthority;
+    private authorizeReading;
+    private readingOperation;
     refreshReading(): void;
     synchronizeReading(cursor?: string, profileId?: string): Promise<import("./readIndex.js").ReadIndexState>;
     /** Explicit text-history acknowledgement; unheard audio stays unread. */

package/lib/runtime/chatSession.js

@@ -31,6 +31,10 @@ export class ChatSession {
     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;
@@ -58,7 +62,7 @@ export class ChatSession {
                     return options.connection.onReach(event);
                 throw new Error("REACH_HANDLER_UNAVAILABLE");
             } });
-        this.reading = new ReadingClient({ ...options.reading, storageScope: JSON.stringify([scope.accountId]), migrateLegacy: true });
+        this.reading = new ReadingClient({ ...options.reading, teamId: scope.teamId, storageScope: JSON.stringify([scope.accountId]), migrateLegacy: 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 });
         this.sender = new DurableChatSender(this.connection, scope, options.onError, { access: () => this.messages.scopeAccess() });
         this.catchUp = new WindowedTasks(1000, error => { if (!this.closed)
@@ -74,7 +78,8 @@ export class ChatSession {
         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 decoded = options.decode(message);
@@ -97,7 +102,8 @@ export class ChatSession {
             this.publishGlobal();
             if (state === "connected") {
                 const since = Date.now();
-                this.catchUp.schedule("scope", () => this.messages.restore(since, options.activeThreadId));
+                this.catchUp.schedule("scope", async () => { if (this.connectionState === "connected" && !this.closed && !this.withdrawn)
+                    await this.messages.restore(since, options.activeThreadId); });
                 if (this.readingStarted)
                     this.reading.refresh();
                 this.wakeCounts();
@@ -132,6 +138,7 @@ export class ChatSession {
                 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;
@@ -139,16 +146,60 @@ export class ChatSession {
     }
     /** 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 ? undefined : this.reading.getSnapshot(); }
+    getReadingSnapshot() { return this.closed || this.withdrawn || !this.readingAllowed ? undefined : this.reading.getSnapshot(); }
     subscribeReading(listener) { if (this.closed || this.withdrawn)
-        return () => { }; return this.reading.subscribe(listener); }
-    refreshReading() { this.assertOpen(); this.reading.refresh(); }
-    synchronizeReading(cursor, profileId) { this.assertOpen(); return this.reading.synchronize(cursor, profileId); }
+        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. */
-    markRead(threadId, messages = []) { this.assertOpen(); return this.reading.markRead(threadId, messages).then(next => { if (this.withdrawn)
-        throw new Error("CHAT_ACCESS_REVOKED"); return next; }); }
-    updateReading(transform) { this.assertOpen(); return this.reading.update(transform).then(next => { if (this.withdrawn)
-        throw new Error("CHAT_ACCESS_REVOKED"); return next; }); }
+    markRead(threadId, messages = []) { return this.readingOperation(() => this.reading.markRead(threadId, messages)); }
+    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"); }
@@ -277,7 +328,7 @@ export class ChatSession {
         }
         if (!threadId)
             throw new Error("INVALID_READING_THREAD");
-        return (event === "played" ? this.reading.recordExplicit(threadId, ids) : this.reading.recordVisible(threadId, ids)).then(next => { this.assertOpen(); return next; });
+        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) {
@@ -297,7 +348,7 @@ export class ChatSession {
             if (event.payload.profileId !== this.options.messages.scope.profileId)
                 throw new Error("Reading reach identity mismatch");
             await this.initialize();
-            await this.reading.synchronize(event.payload.syncCursor, event.payload.profileId);
+            await this.synchronizeReading(event.payload.syncCursor, event.payload.profileId);
             this.assertOpen();
         }
         return "handled";
@@ -378,7 +429,7 @@ export class ChatSession {
         let snapshot = this.snapshots.get(threadId);
         if (!snapshot) {
             const messages = this.messages.getSnapshot(threadId);
-            const state = this.reading.getSnapshot();
+            const state = this.getReadingSnapshot();
             snapshot = { messages: messages?.messages ?? [], hasEarlier: messages?.hasEarlier ?? false, resetVersion: messages?.resetVersion ?? 0, complete: messages?.complete ?? false, outgoing: this.sender.snapshot(threadId), readCounts: this.countSnapshots.get(threadId), unread: state?.threads.some(thread => (thread.conversationId ?? thread.id) === threadId) ? unreadInConversation(state, threadId) : undefined };
             this.snapshots.set(threadId, snapshot);
         }
@@ -425,7 +476,7 @@ export class ChatSession {
     }
     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())
@@ -434,7 +485,7 @@ export class ChatSession {
             const snapshot = this.getSnapshot(threadId);
             return { threadId, lastMessage: snapshot.messages.at(-1), unread: snapshot.unread, outgoingCount: snapshot.outgoing.length };
         });
-        const state = this.reading.getSnapshot();
+        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 };
     }
@@ -482,6 +533,7 @@ export class ChatSession {
         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 () => {
@@ -528,8 +580,10 @@ export class ChatSession {
             if (!this.options.sharedConnection)
                 this.connection.close();
             const senderClosing = this.sender.close();
+            const readingBarrier = Promise.allSettled([...this.acceptedReading]);
+            const readingClosing = readingBarrier.then(() => this.reading.close());
             try {
-                const results = await Promise.allSettled([this.counts?.close(), ...this.countClosings, this.readers.close(), senderClosing, this.reading.close(), this.messages.close(senderClosing)]);
+                const results = await Promise.allSettled([this.counts?.close(), ...this.countClosings, this.readers.close(), senderClosing, readingClosing, this.messages.close(Promise.allSettled([senderClosing, readingBarrier]))]);
                 const failed = results.find((result) => result.status === "rejected");
                 if (failed)
                     throw failed.reason;
@@ -537,6 +591,7 @@ export class ChatSession {
             finally {
                 this.listeners.clear();
                 this.globalListeners.clear();
+                this.readingListeners.clear();
                 this.snapshots.clear();
                 this.countSnapshots.clear();
                 this.historyEdges.clear();

package/lib/runtime/connectivity.d.ts

@@ -0,0 +1,4 @@
+/** Browser connectivity is advisory: only suppress network errors while the
+ * browser explicitly reports offline. Permission and data errors stay visible. */
+export declare function isOffline(): boolean;
+export declare function isOfflineNetworkFailure(error: unknown): boolean;

package/lib/runtime/connectivity.js

@@ -0,0 +1,8 @@
+/** Browser connectivity is advisory: only suppress network errors while the
+ * browser explicitly reports offline. Permission and data errors stay visible. */
+export function isOffline() {
+    return typeof navigator !== "undefined" && navigator.onLine === false;
+}
+export function isOfflineNetworkFailure(error) {
+    return isOffline() && (error instanceof TypeError || error?.name === "AbortError");
+}

package/lib/runtime/durableSender.js

@@ -293,6 +293,7 @@ export class DurableChatSender {
         this.offConnection();
         this.listeners.clear();
         this.channel?.close();
+        this.channel = undefined;
         try {
             await this.ready;
             await Promise.allSettled([...this.accepted, ...this.running.values(), ...(this.revoking ? [this.revoking] : [])]);

package/lib/runtime/messageClient.js

@@ -1,3 +1,4 @@
+import { isOffline, isOfflineNetworkFailure } from "./connectivity.js";
 import { WindowedTasks } from "./coalescer.js";
 import { IndexedDbMessageStore, messageScopeKey, mergeStoredMessage } from "./messageStore.js";
 /** Local-first message facade; hosts never select a cache or network source. */
@@ -48,7 +49,8 @@ export class MessageClient {
             this.invalidate(thread);
         else
             options.onError?.(error, thread); });
-        this.syncTasks = new WindowedTasks(options.syncWindowMs ?? 1000, (error, thread) => options.onError?.(error, thread));
+        this.syncTasks = new WindowedTasks(options.syncWindowMs ?? 1000, (error, thread) => { if (!isOfflineNetworkFailure(error))
+            options.onError?.(error, thread); });
         if (typeof BroadcastChannel !== "undefined") {
             this.channel = new BroadcastChannel(`pmate-chat:${messageScopeKey(options.scope)}${this.storage.namespace === "pmate-chat-messages" ? "" : `:${this.storage.namespace}`}`);
             this.channel.onmessage = event => {
@@ -109,15 +111,17 @@ export class MessageClient {
     subscribeAll(listener) { this.allListeners.add(listener); return () => { this.allListeners.delete(listener); }; }
     /** Close the connection gap for saved windows with four bounded background lanes. */
     async restore(since, threadId) {
+        if (this.closed || this.closing || this.scopeDenied || isOffline())
+            return;
         const queue = (await this.storage.windows()).filter(window => (window.syncedAt ?? 0) < since && !window.revoked && (threadId === undefined || window.thread === threadId));
         await Promise.all(Array.from({ length: Math.min(4, queue.length) }, async () => {
-            while (queue.length && !this.closed && !this.closing) {
+            while (queue.length && !this.closed && !this.closing && !this.scopeDenied && !isOffline()) {
                 const window = queue.shift();
                 try {
                     await this.synchronize(window.thread);
                 }
                 catch (error) {
-                    if (!this.closed && !this.closing)
+                    if (!this.closed && !this.closing && !isOfflineNetworkFailure(error))
                         this.options.onError?.(error, window.thread);
                 }
             }
@@ -198,8 +202,11 @@ export class MessageClient {
     }
     /** Application connection/wake events invalidate, rather than fetching directly. */
     invalidate(thread) {
-        if (!this.closed && !this.closing && !this.revoked.has(thread))
-            this.syncTasks.schedule(thread, () => this.synchronize(thread));
+        if (!this.closed && !this.closing && !this.scopeDenied && !isOffline() && !this.revoked.has(thread))
+            this.syncTasks.schedule(thread, async () => {
+                if (!isOffline())
+                    await this.synchronize(thread);
+            });
     }
     async fallback(thread, limit, before) {
         await this.ensureScope();

package/lib/runtime/messageReaders.js

@@ -1,3 +1,4 @@
+import { isOffline } from "./connectivity.js";
 import { IndexedDbResponseCache, isResponseCacheAuthorityError, assertResponseCacheAccess } from "./responseCache.js";
 import { messageScopeKey } from "./messageStore.js";
 export class MessageReadersError extends Error {
@@ -95,6 +96,8 @@ export class MessageReadersClient {
         const scopeVersion = this.options.access ? await assertResponseCacheAccess(this.options.access) : undefined;
         if (this.lifetime.signal.aborted)
             throw new Error("MESSAGE_READERS_CLOSED");
+        if (isOffline())
+            throw new MessageReadersError(0, "MESSAGE_READERS_OFFLINE_UNAVAILABLE");
         const { token, fetch: fetcher, hubHttpUrl, appId, profileId } = this.options;
         const controller = new AbortController();
         const cancel = () => controller.abort(this.lifetime.signal.reason);

package/lib/runtime/readCounts.js

@@ -1,3 +1,4 @@
+import { isOffline, isOfflineNetworkFailure } from "./connectivity.js";
 import { IndexedDbResponseCache, isResponseCacheAuthorityError, assertResponseCacheAccess } from "./responseCache.js";
 import { messageScopeKey } from "./messageStore.js";
 let subscriptionSequence = 0;
@@ -59,6 +60,8 @@ export class ReadCountsClient {
         return envelope.data;
     }
     subscription(threadId, release) {
+        if (release && isOffline())
+            return Promise.resolve();
         return this.post("/api/social/reading/subscription", { appId: this.options.appId, profileId: this.options.profileId, threadId, clientInstanceId: this.options.clientInstanceId, sequence: nextSubscriptionSequence(), release });
     }
     renew() {
@@ -98,7 +101,8 @@ export class ReadCountsClient {
                 clearInterval(this.heartbeat);
                 this.heartbeat = undefined;
             }
-            this.options.onError?.(error);
+            if (!isOfflineNetworkFailure(error))
+                this.options.onError?.(error);
         }).finally(() => { if (this.subscriptionPending === pending)
             this.subscriptionPending = undefined; });
         this.subscriptionPending = pending;
@@ -197,6 +201,8 @@ export class ReadCountsClient {
                 if (offline || (!force && this.requestedRevision <= this.revision && Date.now() - cached.time < 5000))
                     return;
             }
+            if (isOffline())
+                return;
             const value = await this.post("/api/social/reading/counts", { appId: this.options.appId, profileId: this.options.profileId, threadId, messageIds: ids }, controller.signal);
             if (generation !== this.generation || this.closed || accessVersion !== this.accessVersion)
                 return;
@@ -217,6 +223,10 @@ export class ReadCountsClient {
                 this.renew();
         }
         catch (error) {
+            if (isOfflineNetworkFailure(error)) {
+                this.dirty = false;
+                return;
+            }
             if (!controller.signal.aborted && generation === this.generation && !this.closed) {
                 if (/READ_COUNTS_HTTP_(401|403)/.test(String(error)))
                     this.denyCache();

package/lib/runtime/readIndex.d.ts

@@ -79,7 +79,7 @@ export declare function unreadInThread(state: ReadIndexState, threadId: string):
 };
 export type ReadIndexVersions = Readonly<Record<string, number>>;
 export type ReadIndexTransform = (current: ReadIndexState, versions?: ReadIndexVersions) => ReadIndexState;
-export declare function assertReadIndexVersions(expected: ReadIndexVersions, current?: ReadIndexVersions): void;
+export declare function assertReadIndexVersions(expected: ReadIndexVersions, current?: ReadIndexVersions, teamId?: string): void;
 /** Remove only the withdrawn team's original sources, logical conversations and
  * queued observations. Other teams' pending operations must survive. */
 export declare function removeReadTeam(state: ReadIndexState, teamId: string, knownThreadIds?: readonly string[]): ReadIndexState;

package/lib/runtime/readIndex.js

@@ -165,8 +165,8 @@ export function unreadInThread(state, threadId) {
     return { unreadMessageCount, unreadMentionCount, badgeCount: thread.kind === "group" ? unreadMentionCount : unreadMessageCount };
 }
 function readTeamVersion(versions, team) { return Object.hasOwn(versions, team) ? versions[team] : 0; }
-export function assertReadIndexVersions(expected, current = {}) {
-    const teams = new Set([...Object.keys(expected), ...Object.keys(current)]);
+export function assertReadIndexVersions(expected, current = {}, teamId) {
+    const teams = new Set(teamId === undefined ? [...Object.keys(expected), ...Object.keys(current)] : [teamId]);
     if ([...teams].some(team => readTeamVersion(expected, team) !== readTeamVersion(current, team)))
         throw new Error("READ_SCOPE_CHANGED");
 }

package/lib/runtime/readingClient.d.ts

@@ -5,6 +5,7 @@ export type ReadingClientOptions = {
     profileId: string;
     sessionToken: string;
     hubHttpUrl: string;
+    teamId?: string;
     persistence?: ReadIndexPersistence;
     storageScope?: string;
     migrateLegacy?: boolean;
@@ -21,6 +22,7 @@ export declare class ReadingClient {
     private closing?;
     private revoking?;
     private versions?;
+    private prepared;
     private accepted;
     private persistence;
     private sync;
@@ -41,7 +43,9 @@ export declare class ReadingClient {
     refresh: () => void;
     synchronize(targetCursor?: string, profileId?: string): Promise<ReadIndexState>;
     update(transform: (state: ReadIndexState) => ReadIndexState): Promise<ReadIndexState>;
+    private updateScoped;
     prepareTeam(teamId: string, version: number): Promise<void>;
+    private assertThreadTeam;
     markRead(threadId: string, messages?: readonly ConversationReadMessage[]): Promise<ReadIndexState>;
     recordVisible(threadId: string, messageIds: string[]): Promise<ReadIndexState>;
     recordExplicit(threadId: string, messageIds: string[]): Promise<ReadIndexState>;

package/lib/runtime/readingClient.js

@@ -1,3 +1,5 @@
+import { isValidChatTeamId } from "./thread.js";
+import { isOffline, isOfflineNetworkFailure } from "./connectivity.js";
 import { recordConversationRead } from "./conversationRead.js";
 import { BatchedReadIndex } from "./batchedReadIndex.js";
 import { WindowedTasks } from "./coalescer.js";
@@ -12,6 +14,7 @@ export class ReadingClient {
     closing;
     revoking;
     versions;
+    prepared = new Map();
     accepted = new Set();
     persistence;
     sync;
@@ -25,6 +28,8 @@ export class ReadingClient {
     generation = 0;
     constructor(options) {
         this.options = options;
+        if (options.teamId !== undefined && !isValidChatTeamId(options.teamId))
+            throw new Error("INVALID_READ_TEAM");
         const storage = options.persistence ?? (this.storage = new IndexedDbReadIndex(globalThis.indexedDB, "pmate-social-read-index", options.storageScope, options.migrateLegacy));
         this.backing = storage;
         this.persistence = new BatchedReadIndex(storage);
@@ -40,7 +45,7 @@ export class ReadingClient {
         this.listeners.forEach(listener => listener());
     }
     failed(error) {
-        if (this.closed)
+        if (this.closed || isOfflineNetworkFailure(error))
             return;
         this.options.onError?.(error);
         if (/HTTP_(400|401|403)/.test(String(error)) || (typeof navigator !== "undefined" && !navigator.onLine) || this.retry)
@@ -63,8 +68,9 @@ export class ReadingClient {
         this.refresh();
     }
     refresh = () => {
-        if (!this.closed)
-            this.tasks.schedule("reading", async () => { await this.synchronize(); });
+        if (!this.closed && !isOffline())
+            this.tasks.schedule("reading", async () => { if (!isOffline())
+                await this.synchronize(); });
     };
     async synchronize(targetCursor, profileId) {
         if (this.closed)
@@ -92,6 +98,11 @@ export class ReadingClient {
         throw new Error("Reading projection has not reached the announced version");
     }
     update(transform) {
+        // Advanced transforms may replace profile-wide state. Typed observation
+        // methods below only derive changes for their configured team.
+        return this.updateScoped(transform);
+    }
+    updateScoped(transform, teamId) {
         if (this.closed)
             return Promise.reject(new Error("READING_CLIENT_CLOSED"));
         // One shared metadata read per local authority generation, rather than one
@@ -100,7 +111,7 @@ export class ReadingClient {
         const task = (async () => {
             const expected = await versions;
             const next = await this.persistence.update(this.options.appId, this.options.profileId, (state, currentVersions) => {
-                assertReadIndexVersions(expected, currentVersions);
+                assertReadIndexVersions(expected, currentVersions, teamId);
                 return transform(state);
             });
             if (!this.closed) {
@@ -109,28 +120,48 @@ export class ReadingClient {
                     this.refresh();
             }
             return next;
-        })().catch(error => { if (String(error).includes("READ_SCOPE_CHANGED"))
-            this.versions = undefined; throw error; });
+        })().catch(error => {
+            if (String(error).includes("READ_SCOPE_CHANGED")) {
+                if (teamId !== undefined)
+                    this.withdraw();
+                else
+                    this.versions = undefined;
+            }
+            throw error;
+        });
         this.accepted.add(task);
         void task.finally(() => this.accepted.delete(task)).catch(() => { });
         return task;
     }
-    async prepareTeam(teamId, version) {
+    prepareTeam(teamId, version) {
         if (this.closed)
-            throw new Error("READING_CLIENT_CLOSED");
-        if (version > 0) {
-            await this.persistence.invalidateTeam(this.options.appId, this.options.profileId, teamId, version);
+            return Promise.reject(new Error("READING_CLIENT_CLOSED"));
+        if (!isValidChatTeamId(teamId) || !Number.isSafeInteger(version) || version < 0)
+            return Promise.reject(new Error("INVALID_READ_SCOPE_VERSION"));
+        const previous = this.prepared.get(teamId);
+        if (previous && previous.version >= version)
+            return previous.task;
+        const task = (async () => {
+            if (version > 0)
+                await this.persistence.invalidateTeam(this.options.appId, this.options.profileId, teamId, version);
             this.versions = undefined;
-        }
+        })().catch(error => { if (this.prepared.get(teamId)?.task === task)
+            this.prepared.delete(teamId); throw error; });
+        this.prepared.set(teamId, { version, task });
+        return task;
+    }
+    assertThreadTeam(state, threadId) {
+        if (this.options.teamId !== undefined && state.threads.some(thread => (thread.id === threadId || thread.conversationId === threadId) && thread.teamId !== undefined && thread.teamId !== this.options.teamId))
+            throw new Error("READ_CONVERSATION_TEAM_MISMATCH");
     }
     markRead(threadId, messages = []) {
-        return this.update(state => recordConversationRead(state, threadId, messages));
+        return this.updateScoped(state => { this.assertThreadTeam(state, threadId); return recordConversationRead(state, threadId, messages); }, this.options.teamId);
     }
     recordVisible(threadId, messageIds) { return this.record(threadId, messageIds, "visible"); }
     recordExplicit(threadId, messageIds) { return this.record(threadId, messageIds, "explicit"); }
     record(threadId, ids, readPolicy) {
         const messageIds = [...new Set(ids)];
-        return this.update(state => messageIds.reduce((next, messageId) => recordReadIntent(next, { threadId, messageId, readPolicy, operationId: crypto.randomUUID() }), state));
+        return this.updateScoped(state => { this.assertThreadTeam(state, threadId); return messageIds.reduce((next, messageId) => recordReadIntent(next, { threadId, messageId, readPolicy, operationId: crypto.randomUUID() }), state); }, this.options.teamId);
     }
     withdraw() { this.stop(); }
     stop() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.12.0-next.23",
+  "version": "0.12.0-next.25",
   "description": "Cross-platform PMate chat input components, voice input primitives, and ASR helpers",
   "type": "module",
   "main": "./lib/index.js",